jrgilbertson Publishing Release Notes
Create polished, high-quality release notes from a repository changelog.
Workflow
Before doing anything else, stop and think carefully about every possible interpretation of the request.
Ask the user one question at a time about the audience, tone, release scope, source material, and desired length, even when the answer is already present in the request or repository.
Read the changelog and draft release notes with a summary, highlights, and upgrade guidance. Be thorough, clear, and compelling.
Reread the draft twice. Then ask an independent agent to verify that the writing is polished and explain why every section is ready.
When replacing an existing release-notes file, preserve this order because a formatter or validator can fail after partially processing a draft:
- Write the complete replacement to a temporary sibling file.
- Run the repository's documented formatter and validator on that temporary file.
- Replace the existing release-notes file only after both checks pass.
- If either check fails, leave the existing file untouched and report the temporary file's location.
Present the final release notes and confirm that the work is completely and comprehensively finished.