Files
gstack/ship/sections/changelog.md
garrytanandcapy-ai[bot] 2d73fadd56 feat(ship): version-less repos, docs-audit record and caps, the frozen-scope paid case, and the review-loop follow-ups
Follow-up to the review-loop convergence PR: Step 12 and the CHANGELOG step skip cleanly in a repository with no version source (receipt version "none"); the receipt records the docs audit outcome and the owner exception (DOCS_AUDIT_BLOCKED without one) and a policy may declare doc caps (gstack-ship-receipt docs-caps); docs/unattended.md names the READY evidence and the cross-family outside voice; the ship-frozen-scope-convergence behaviour case runs the generated Step 9.4 under review_scope frozen through the real binaries; carry probes git >= 2.39 (RECEIPT_GIT_TOO_OLD); defer passes the repository to gh repo view positionally and names its search limit; late defers count without being passes; reviewers diff from RANGE_BASE on pass 2+; the cap check runs before edits; --review-fanout batches specialists by free slots; read --check-prose compares quoted counters with the receipt (RECEIPT_PROSE_MISMATCH); checklist rule ids prereg-with-results and test-keyboard-count-loop; gstack-coauthor-trailers.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-10-26 20:49:56 +00:00

2.5 KiB

Step 13: CHANGELOG (auto-generate)

  1. Read CHANGELOG.md header to know the format.

  2. First, enumerate every commit on the branch:

    git log origin/<base>..HEAD --oneline
    

    Copy the full list. Count the commits. You will use this as a checklist.

  3. Read the full diff to understand what each commit actually changed:

    git diff origin/<base>
    
  4. Group commits by theme before writing anything. Common themes:

    • New features / capabilities
    • Performance improvements
    • Bug fixes
    • Dead code removal / cleanup
    • Infrastructure / tooling / tests
    • Refactoring
  5. Write the CHANGELOG entry covering ALL groups:

    • If existing CHANGELOG entries on the branch already cover some commits, replace them with one unified entry for the new version
    • Categorize changes into applicable sections:
      • ### Added — new features
      • ### Changed — changes to existing functionality
      • ### Fixed — bug fixes
      • ### Removed — removed features
    • Write concise, descriptive bullet points
    • Insert after the observed file header, before the first release entry, dated today
    • Format: ## [X.Y.Z.W] - YYYY-MM-DD
    • Voice: Lead with what the user can now do that they couldn't before. Use plain language, not implementation details. Never mention TODOS.md, internal tracking, or contributor-facing details.
  6. Cross-check: Compare your CHANGELOG entry against the commit list from step 2. Every user-facing change in that list must be represented; add any that is missing. Commits with no user-facing effect (merges, version bumps, fixes to work introduced earlier on this branch) need no bullet. The entry must reflect every user-facing theme.

Do NOT ask the user to describe changes. Infer from the diff and commit history.

NO_VERSION (Step 12): skip this step; write no CHANGELOG entry or version header.

No CHANGELOG: when the policy's changelog is null, or the file it names (CHANGELOG.md by default) is absent at HEAD, print one line, CHANGELOG: skipped (none at <path>), write nothing and never create the file; Step 19's PR body carries the release notes instead. A repository with neither a version source nor a CHANGELOG ships with both lines printed and a receipt whose version is "none" (docs/ship-policy.md#ship-receipt).