FRB Write Changelog

Step 1: Inspect CHANGELOG.md

Read the top of CHANGELOG.md.

• Confirm the target version section exists, or add it.
• Keep the existing V2 "what's new" header line.
• Inspect git diff -- CHANGELOG.md before editing.
• Replace only the target section if it already contains a placeholder such as * TODO.

Step 2: Identify the previous release tag

Find the latest release tag before the target version.

git tag --sort=-creatordate | head -n 20

Use that tag as the lower bound for the new changelog entry.

Step 3: Collect merged PRs

Use GitHub CLI to collect merged PRs after the previous version.

gh pr list --state merged --limit 200 --json number,title,author,mergedAt,baseRefName,url
gh pr view <number> --json number,title,author,url

Use the previous version as the lower bound when deciding which merged PRs belong to the target release.

Step 4: Filter and normalize

Keep all PRs in merged status that belong to the release range.

• Exclude unmerged PRs.
• Exclude PRs outside the release range.
• When refreshing an already-published release, use both the previous release timestamp and the target release tag timestamp so later post-release PRs are not pulled into the published section.
• Do not filter by target branch.
• Keep docs, CI, and chore PRs if they are merged in the range.
• Exclude only all-contributors PRs such as docs: add <name> as a contributor for code/doc; do not exclude ordinary documentation PRs whose titles start with docs: add.

Normalize titles before writing.

• Rewrite noisy internal titles into concise changelog language.
• Avoid duplicate summaries for split or "continued" PRs.
• Preserve repo-specific capitalization such as CI, GitHub, Flutter, Rust, DCO, and V1.

Step 5: Write the section

Match the existing changelog style.

• Write each item as * Summary #1234.
• Append (thanks @username) for every third-party human-authored PR in the release range, including docs, CI, chore, tooling, and feature PRs.
• When a changelog entry combines local maintainer PRs with a third-party PR, append the third-party thanks to that combined entry.
• If multiple third-party authors appear in one combined entry, include each author in the same entry.
• Place entries with (thanks @username) before entries without thanks.
• Within the thanks group and the no-thanks group, keep items in merge order from newest to oldest unless the surrounding section clearly uses another order.

Edit only CHANGELOG.md. Do not manually edit generated files for this task.

Step 6: Review and commit

Review the final diff.

• Confirm the change is limited to the target release section.
• Confirm wording and ordering match nearby release sections.
• Create a small atomic commit after finishing the edit.

Step 7: Run mechanical verification

Run the changelog verifier after finishing the draft.

gh pr list --state merged --limit 200 --json number,title,author,mergedAt,baseRefName,url > /tmp/frb-merged-prs.json
uv run --script .claude/skills/frb-write-changelog/verify_changelog.py \
  --version <VERSION> \
  --previous-release-time <PREVIOUS_RELEASE_TIMESTAMP> \
  --release-time <TARGET_RELEASE_TIMESTAMP> \
  --merged-prs-json /tmp/frb-merged-prs.json

The verifier checks that:

• PR numbers in the target section are complete, not duplicated, and not unexpected.
• Third-party thanks authors are complete and not unexpected, including ordinary documentation PR authors. The same author may be thanked on multiple entries.
• Entries with third-party thanks appear before entries without thanks.
• docs: add <name> as a contributor ... all-contributors PRs are ignored.

Use --ignore-pr <NUMBER> only for a documented intentional exclusion. Use --extra-local-pr <NUMBER> for a stacked local maintainer PR that belongs in the changelog but is not present in the merged PR JSON yet. Use --extra-thanks-author <LOGIN> only for a verified co-author or contributor credited by a release-range PR even though their source PR falls outside the release range; record the source PR and reason in the release journal.

Apply any confirmed fixes, then re-run the verifier.

Step 8: Ask the user to review ordering

Tell the user the changelog draft is complete and ask for a manual review.

• Ask the user to review the wording.
• Ask the user to review the ordering of entries.
• Adjust the ordering if the user wants a different presentation from the mechanically collected order.

Step 9: Re-verify after human edits

Run the mechanical verifier again after the user finishes manual edits.

• Confirm there are no missing, duplicated, or extra PR numbers.
• Confirm there are no missing or unexpected third-party thanks authors.
• Confirm entries with third-party thanks appear before entries without thanks.
• Apply any confirmed fixes, then do one final diff check.

If the user explicitly wants an independent review, ask a separate reviewer or subagent to compare the final CHANGELOG.md against the same merged PR list.