Keep three kinds of text separate: the short commit description, detailed notes on that commit, and release-wide marketplace publication notes. Writing detailed notes does not publish a release.
The #297 interface is implemented; see verification evidence and remaining live checks.
If installed source branch commit --help lacks the notes options, check the installed build;
version 0.5.8 alone does not distinguish builds before and after the merge. Prepare the notes file
without bypassing the CLI's validation, organization checks, confirmation, or explicit selection.
Choose the requested operation
- Draft notes: inspect changes and prepare text/files; drafting alone does not authorize a commit.
- Commit with notes: apply the draft workflow, preserve the authorized branch/config scope, then use the CLI transport below.
- Read notes: follow retrieval below; no mutation is needed.
- Add notes to an already completed commit: inspect available metadata, but do not create a replacement commit. #297 defines commit-time input, not an edit-existing-commit operation; report that boundary if no supported edit operation exists.
Draft detailed notes
Use commit-message-generator for change inspection, traceability, title/description, and detailed engineering context. Apply its drafting rules to the selected changes. For a partial commit, describe only selected configurations and relevant non-config changes; distinguish remaining branch work from what this commit will contain.
Save the detailed section as UTF-8 commit-notes.md. Include the concrete behavior change, rationale,
relevant work-item references, validation actually performed, and material limitations. Preserve
Unicode, Markdown indentation, hard-break spaces, and line endings. Use file tools or a quoted
heredoc rather than shell interpolation of prose containing $ or backticks.
Keep the short description separate. The existing SaveCommitMessage one-shot integration has
its own delivery contract; this CLI feature does not change its parameters or imply SideKick
support. A CLI commit is performed only when that operation is part of the user's request.
Attach at commit time
Use the implemented notes-file interface:
dxs source branch commit <branch_id> \
--title "Fix split-shipment allocation" \
--description "Prevent duplicate allocation." \
--release-notes-file commit-notes.md \
--config <selected_reference> \
--dry-run
Use repeatable --config for selected changes, or --all-changes only when all changed configs
are in scope. The alternative --release-notes TEXT is intended for short inline content; the two
notes options are mutually exclusive. Conflicting options, unreadable files, and invalid UTF-8
fail before HTTP requests. Check the exact selection and commit_result.commitReleaseNotes in
dry-run output. Omitted notes omit that field; explicit empty/whitespace notes remain distinct.
Dry run does not echo the short description and does not exercise server validation, organization
ownership checks, or confirmation. It is not a completed commit.
After scope and authorization are established, run the same command without --dry-run, preserving
the CLI's normal validation and confirmation. --force skips validation and confirmation for
commits; with explicit --config it also bypasses changed-reference preflight. Do not add it
merely to get past a finding or an interactive prompt. This differs from
env deploy --force, which skips confirmation only.
The request field is releaseNotes; returned metadata is commitReleaseNotes. Omitted notes keep
existing callers working. The API falls back to the short description for absent, empty, or
whitespace-only notes; older values may also have been backfilled from descriptions. A nonempty
read value therefore does not prove detailed engineering notes were authored.
Inspect the actual commit result. Report any continuation feature branch created for unselected
changes (commit_result.new_branch_id; raw newBranchId remains under commit_result.result).
Success does not itself return stored notes; retrieve them separately. On an uncertain outcome, reconcile
through read-only branch/history queries rather than replaying the mutation.
Retrieve notes
Use structured JSON to inspect the actual response without formatting away Markdown whitespace:
dxs -O json source log --branch <branch_id>
dxs -O json source branch show <branch_id>
dxs -O json source history <reference_name> --branch <branch_id>
Match the exact commit/branch/config identity; do not take the newest log entry as proof of which
commit was requested. The read field is commitReleaseNotes, distinct from commitMessage and
commitDescription. Branch logs use commits[], batch source log --branches A,B uses
branch_logs[].commits[], branch detail uses branch, and configuration history (including
--diff) uses versions[]. Missing fields stay missing. Default concise output may omit
nulls; absence is not a command failure. Use the global dxs --full -O json … form when diagnosing present versus null fields; the history command’s own --full has a separate diff-content meaning.
When enriching release notes, consume detailed text alongside work items and diffs. Release-to-release
source compare and source release-notes reconstruct committed_branches without detailed notes;
enrich each returned commit ID through branch detail/history. Non-release source compare can
preserve API-supplied notes in branch_comparison.commits; inspect its actual fields. Record absent
or summary-only notes without treating them as lost commits, and continue release synthesis.
On readback after an authorized write, compare the supplied text with stored notes, allowing only
the documented API fallback for empty/whitespace input. If formatting differs, preserve evidence
and report it; do not rewrite the commit. JSON and YAML preserve commitReleaseNotes exactly,
including Unicode, LF/CRLF/CR line endings, indentation, hard-break spaces, and leading/trailing
newlines. This fidelity guarantee is field-specific; do not generalize it to all CLI prose.
Offline serialization is verified; a live write/read round trip remains a check for an independently
authorized real commit, as recorded in the checklist.
Return
Return the title, short description, detailed notes file/text, selected configurations, and whether
the result was drafted, dry-run only, committed, or retrieved. Include readback evidence and any
continuation branch or unresolved transport/formatting issue. Marketplace publish --notes and
cascade --release-notes retain their publication meaning and are not commit-note substitutes.