Cut a release and write the notes

Before tagging anything

1. Pick the commit, and check it. The tag goes on a commit whose checks are green on the default branch — not on a branch head, not on a commit whose checks are still running.
2. Read what is in it. List the merges since the previous tag. If anything in that list changes a database schema, a configuration default, or a public interface, the release notes have a section about it and the deploy has a step.
3. Decide the version by what changed, not by habit: anything that makes an existing caller wrong is a major; new capability is a minor; everything else is a patch.

The notes

Write for somebody deciding whether to upgrade today.

• One opening sentence naming the most useful thing in the release.
• What is new, each item one line, in the words of the person using it — the feature, not the pull request title.
• What is fixed, only the ones a user would have noticed.
• What breaks, and what to do about it. This section goes above the others when it is not empty.
• Anything needed at upgrade time: a migration to run, a variable to set, an order to do things in.

Leave out internal refactors, dependency bumps and test changes. They are in the commit list for anyone who wants them, and putting them in the notes buries the three lines that matter.

Then

Publish the release, announce it in one Slack message linking the notes, and move the tickets it closes to done in Linear or Jira with the version on them.

Stop and ask

• Before tagging anything as a major version.
• When the release contains a schema change that cannot be rolled back — that needs a person choosing a moment.