draft-release-notes

Draft Release Notes

Draft release notes from verified repository evidence. Keep complete, tag-specific release history in GitHub Releases. Update the documentation-site release-notes page only when the documentation-visible release summary changes.

Gather Evidence

Run the read-only helper with explicit release refs and the exact target release version:

python3 .agents/skills/draft-release-notes/scripts/collect_release_evidence.py \
  --previous <previous-release-tag-or-branch> \
  --current HEAD \
  --version <release-version>

For a patch release, use the previous stable tag as --previous. For a new release line, use the previous release branch or tag. The report verifies both refs, inspects the release-notes page at each ref, identifies version text, and groups commits into review candidates. Treat the groups as an evidence index, not publication-ready copy.

Workflow

1. Establish the release branch and target version. Preserve unrelated working-tree changes; do not stash or discard them.

   • If the user supplied a version, derive release/<major>.<minor> and check out that branch.
   • If the user did not supply a version, require the current branch to match release/<major>.<minor>; do not infer a release line from package metadata or Git history.
   • Read the target version from Cargo.toml. When the user supplied a version, require it to match the package version.

   RELEASE_VERSION_INPUT="${RELEASE_VERSION_INPUT:-}"
   if [[ -n "${RELEASE_VERSION_INPUT}" ]]; then
     if [[ ! "${RELEASE_VERSION_INPUT}" =~ ^[0-9]+\.[0-9]+(\.[0-9]+)?$ ]]; then
       echo "Error: release version must be <major>.<minor> or <major>.<minor>.<patch>" >&2
       exit 1
     fi
     RELEASE_LINE="$(printf '%s' "${RELEASE_VERSION_INPUT}" | cut -d. -f1,2)"
     if [[ "${RELEASE_VERSION_INPUT}" =~ ^[0-9]+\.[0-9]+$ ]]; then
       EXPECTED_VERSION="${RELEASE_VERSION_INPUT}.0"
     else
       EXPECTED_VERSION="${RELEASE_VERSION_INPUT}"
     fi
     RELEASE_BRANCH="release/${RELEASE_LINE}"
     git switch "${RELEASE_BRANCH}"
   else
     RELEASE_BRANCH="$(git branch --show-current)"
     if [[ ! "${RELEASE_BRANCH}" =~ ^release/([0-9]+\.[0-9]+)$ ]]; then
       echo "Error: supply a release version or check out release/<major>.<minor>" >&2
       exit 1
     fi
     RELEASE_LINE="${BASH_REMATCH[1]}"
   fi
   
   TARGET_VERSION="$(python -c "import tomllib; print(tomllib.load(open('Cargo.toml', 'rb'))['workspace']['package']['version'])")"
   if [[ -n "${RELEASE_VERSION_INPUT}" ]] && [[ "${TARGET_VERSION}" != "${EXPECTED_VERSION}" ]]; then
     echo "Error: ${RELEASE_BRANCH} declares ${TARGET_VERSION}, not ${EXPECTED_VERSION}" >&2
     exit 1
   fi
   

2. Create a new local branch from the release branch for the release-notes work. Let the command fail rather than replacing an existing branch:

   git switch -c "docs/create-release-notes-${TARGET_VERSION}" "${RELEASE_BRANCH}"
   

3. Run the helper. It reports an absent prior release-notes page without failing, which is expected for early release branches.

4. Verify each candidate claim in the changed public docs, API types, command help, or source before including it. Prioritize breaking changes, migrations, user-visible features, and ongoing support limitations.

5. For a patch release, identify the affected behavior and state whether public APIs, configuration, or dependency contracts changed.

6. Update only this page unless the release changes its route or entry point:

   • docs/about-nemo-fabric/release-notes.mdx Leave it unchanged when a patch release does not alter the documentation-visible summary, compatibility guidance, support status, or limitations.

7. Keep the existing page role:

   • release-notes.mdx gives the current-release summary, compatibility notes, scope, and curated feature links.
   • release-notes.mdx groups notable changes by user-facing theme.
   • release-notes.mdx records current limitations.

8. Preserve MDX front matter and the JSX SPDX comment. State the full history is available in GitHub Releases. Do not create a changelog.

9. Update the Roadmap section in README.md, removing items implemented or fixed by changes in the current release.

10. Run the validation checks detailed in Validate.

11. If docs/about-nemo-fabric/release-notes.mdx or README.md changed, commit the release-notes page and README with a signed-off commit after validation succeeds:

    git add docs/about-nemo-fabric/release-notes.mdx README.md
    git commit -sm "Drafting release notes for v${TARGET_VERSION}"
    git push -u upstream HEAD
    

12. If docs/about-nemo-fabric/release-notes.mdx or README.md changed, use the prepare-pr skill to open a pull request from the release-notes branch to ${RELEASE_BRANCH}. Use this title:

    docs: Release notes for v${TARGET_VERSION}
    

    If docs/about-nemo-fabric/release-notes.mdx and README.md are unchanged, skip steps 11 and 12. Do not create a release-notes commit or pull request.

Validate

Run the helper for the target release and review every public claim. If the documentation page changed, run:

git diff --check
just docs

Check product names, commands, package names, support claims, and links against the current repository before handing off the draft.