Write a categorized GitHub Release release notes for the just-tagged version and write it back to the Release: materials → categorize → write to disk → gh release create/edit → verify. Applies to any tag-push → GitHub Release project—npm packages or non-npm projects (desktop software). Templates and anti-patterns are in references/release-notes-guide.md, this document only defines the process.
Execution notes
Release notes are published publicly, and the readers are end users (in the npm case, calling developers). Quality red line: every entry states "what changed for the reader", not a pile of commit titles; delete entire empty categories instead of leaving placeholders.gh release create/edit Before --help verify the flags, don't assemble from memory.
The body of the release notes is always in English—the referenced template skeleton is already in English, and the body (highlights section, bug entries, Breaking Changes migration notes) is likewise not written in Chinese.
Steps
1. Recon and materials
Completion criteria: materials complete—full commit list, PR context (if merged via PR), the repo's Release convention confirmed, and the tag name matches the version to be released (for desktop projects, if the version is maintained in a manifest, verify it as well).
- First confirm the repo convention: does this repo create GitHub Releases?
gh release listis empty or historical versions never had a release → skip this skill per the repo convention, don't take it upon yourself to create a release. git log <上一个 tag>..HEAD --onelineGet the full commit list—get it all before writing, don't read while writing.- The repo merges via PR →
gh pr list --state merged --search "merged:>=<上次发布日期>"add the PR description as material. - Details of material sources follow the "material sources" section of the guide.
2. Categorize
Completion criteria: every entry holds true for the reader (not a pile of file names/function names); Breaking Changes include migration methods; empty categories deleted.
- Categorize per the guide's structural template (Features / Fixes / Docs & Chore / Breaking Changes).
- The highlights section uses one or two sentences to state "what changed for the reader in this version", not which code changed.
- Bug fix entries state the previous symptom clearly, so readers can judge whether it's the one they encountered.
3. Write to disk
Completion criteria: the organized notes are written to a local file, placed in the OS temp directory (Windows $env:TEMP\release-notes-<tag>.md;Linux/WSL/macOS ${TMPDIR:-/tmp}/release-notes-<tag>.md).
Do not write into the repo directory—release notes are not repo content, a temp file path is enough.
4. Show and confirm
Completion criteria: the user has seen the full organized notes and explicitly agreed to write them.
- Show the full organized notes, and point out that the next step is a write operation to the Release (
gh release create/edit)。 - Before a write operation (publishing externally), must wait for explicit user consent; if only a draft is wanted, stop after showing.
5. Write to the Release
Completion criteria:gh release view <tag> Confirm the notes in the Release are the organized version, not a one-line compare link.
- First check whether
gh release view <tag>exists: does not exist →gh release create <tag> --title <tag> --notes-file <文件>; already exists →gh release edit <tag> --notes-file <文件>。 - Desktop workflows almost always create a Release with artifacts first, so you can only edit; using create on an existing Release will error or create an empty Release with no artifacts.
6. Verify and wrap up
Completion criteria:gh release view <tag> output confirmation; the delivery note states the version number, verification method, and skipped items.
Context differences
- Version source:The version has already been determined; this skill only reads the tag name. In the npm workflow, the version is determined by the bump step of the release skill; for desktop projects, the tag is the version.
- create / edit probability:The workflow is always "check first, then decide"; the desktop workflow almost always creates the Release with artifacts first (→ edit), while npm repositories often never create one (→ create). The probability only affects expectations, not the workflow.
- Breaking Changes semantics:Desktop software = changes that require user action (raised system requirements, configuration file format changes, removed features); npm package = API contract changes. For how to write them, see the template section in the guide.
Related skills
- npm-release — Step 7 of the npm package release workflow delegates to this skill to write the release notes; the version number has already been determined by its bump step.