Relmio changelog steward

Write release notes for people deciding whether and how to upgrade. A release note is a curated explanation of user impact, not a commit log, a contributor list, or an autogenerated What's Changed section.

Establish the evidence

1. Choose the release mode before drafting:

   • New release: use the last published tag as the baseline and the release commit as the target. Before the tag exists, make the draft clear that its provisional range is v<previous>..HEAD.
   • Existing release: use the two existing tags exactly: v<previous>..v<target>. Read the current GitHub release body before replacing it.

2. Inspect the repository and exact range. Do not infer scope from a branch name or a remembered PR:

   git tag --sort=-version:refname
   git show -s --format='%D%n%ad%n%s%n%b' --date=short v<target>
   git log --format='%H%n%h %s%n%b%n---' v<previous>..v<target>
   git diff --name-status v<previous>..v<target>
   git log --merges --format='%h %s' v<previous>..v<target>
   

   Use git diff v<previous>..v<target> -- <path> and git show <commit> for changed user-facing files, tests, documentation, and release metadata.

3. Inspect every PR reference found in the range (for example, #123). When GitHub CLI access is available, verify its title, merged commit, files, and description rather than trusting only the merge title:

   gh pr view 123 --json number,title,body,mergeCommit,mergedAt,files
   

4. Make a compact coverage list before writing: each user-visible change or relevant PR must map to a release-note bullet, be consolidated into one related bullet, or be explicitly excluded as no user impact. Reconcile the list with both git log and git diff --name-status so documentation, installer, metadata, and regression-test changes are not silently omitted.

5. Read CHANGELOG.md, package.json, and package-lock.json. Describe only code and documentation in the chosen range; do not include Unreleased or future work. Keep tokens, private infrastructure, and live credentials out of the notes.

Choose the semantic version

Relmio is pre-1.0. Apply its published convention consistently:

• Increment z in 0.y.z for backward-compatible fixes, documentation, or small maintenance.
• Increment y for a meaningful new capability, workflow, or compatibility surface. Describe 0.y.0 as a major feature milestone for users, while retaining the pre-1.0 version number.
• Use 1.0.0 only when the project declares a stable public API. After 1.0, use the normal SemVer major/minor/patch meanings, including a major bump for breaking public changes.

Never reuse a published version. For a new release, confirm that v<version> does not already exist before creating release metadata.

Write the project changelog entry

Keep ## Unreleased at the top. Add the newest dated entry directly below it as ## [X.Y.Z] - YYYY-MM-DD. Use only populated sections, in this order:

1. Added for new commands, pages, workflows, or supported capabilities.
2. Changed for intentional behavior, UX, compatibility, or documentation.
3. Fixed for corrected failures and regressions.
4. Security for security-boundary or dependency fixes.

Phrase each bullet as user outcome first, followed by the important limit or reason. Consolidate related commits; do not duplicate every commit or test. For a pre-1.0 feature milestone that summarizes earlier patches, provide a short, accurate consolidation of the relevant release line rather than copying its entire history.

Write the GitHub release body

Use real Markdown line breaks and blank lines. Draft into a file and inspect the rendered structure mentally before publishing: literal \\n characters and an escaped single-paragraph body are defects.

Patch release

Use only populated standard sections, in order: Added, Changed, Fixed, and Security. Keep it concise; a patch can contain any supported combination, not only Fixed:

Relmio X.Y.Z <one-sentence user-facing outcome>.

## Changed

- <Newly available capability or intentional user-visible behavior.>

## Fixed

- <Impact and affected workflow.>
- <Regression protection, when it matters to users or maintainers.>

**Full Changelog**: [v<previous>...v<target>](https://github.com/<owner>/<repo>/compare/v<previous>...v<target>)

Omit empty sections. Keep a patch release to one short lead and one-to-four impact bullets.

Pre-1.0 feature milestone or stable major release

Use a stronger short opening and scannable highlights; retain only the context that helps users understand the milestone:

Relmio X.Y.0 is a <pre-1.0 major feature milestone/stable major release> that <primary user value>.

## Highlights

- <Primary new workflow and its benefit.>
- <Docs, compatibility, or follow-on workflow that users need.>

## Since v<baseline>

- <Concise, factual consolidation of relevant prior releases.>

## Validation

- <Only checks and results recorded by the release evidence.>

**Full Changelog**: [v<baseline>...v<target>](https://github.com/<owner>/<repo>/compare/v<baseline>...v<target>)

Use an Upgrade notes section instead of—or in addition to—Validation only when a user needs a migration, configuration, or compatibility warning.

Do not use gh release create --generate-notes, GitHub's autogenerated What's Changed dump, raw commit lists, contributor statistics, or an unformatted prose blob when curated notes are requested. Do not claim a test, availability state, security property, compatibility result, or deployment outcome unless the selected range, existing release body, or recorded release evidence supports it.

Synchronize release metadata

For a new release, the same version must appear in:

• package.json;
• both version fields in package-lock.json;
• the newest CHANGELOG.md heading;
• the annotated Git tag v<version> on the exact release commit;
• the npm package and GitHub release after publication.

Run npm run release:check before committing. Do not hand-edit a generated tarball or claim a tag/npm release exists until the external write succeeds.

Edit an existing GitHub release safely

Editing prose is not a new release. First confirm the existing tag and release target, then prepare a local notes file with real newlines:

git rev-parse -q --verify refs/tags/v<target>
gh release view v<target> --json tagName,targetCommitish,url,body

Treat an exact, explicit current user instruction to edit the named release body as authorization for this remote write. Otherwise, show the complete replacement draft and obtain final human confirmation before the remote write. Then edit only the body:

gh release edit v<target> --notes-file <draft.md>

Never use gh release create, delete and recreate the release, create another tag, move a tag, or force-push while updating an existing release body. Verify the edited body and target afterward with gh release view.

Verify the release

For a new release, run the repository's full check, dependency audit, package build, and package preview. Review the diff for accidental credentials or private infrastructure details. After publication, confirm the tag points to the merged commit and query npm anonymously for the exact version and integrity. For an existing-release text edit, re-check the tag target and rendered Markdown body; do not rerun publication or mutate release metadata.