SuperAPI AI Directory

commit-release-notes

General & other

View repository

Updated 10-15 20:33

About this skill

Commit Release Notes

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.