Style guide: Release notes in commit messages

PSA: We would like all contributors to start including release-note-ready descriptions of their changes in commit messages, to make it easier to compile our release notes.

The commit message section of has been updated:

Does this apply to less visible things like refactorings and features that aren’t ready?

No, only for user-visible changes. Refactorings and test-only changes aren’t mentioned in the release notes. New features aren’t mentioned in the nodes until they’re ready. If it’s not obvious from the rest of the commit message you can say something like “Release Note: No visible change”.

Should non-user-visible changes explicitly mention that, just to ensure it wasn’t overlooked, e.g. “Release Note: none” or something?

Usually it’s pretty obvious from the rest of the commit message when something is just a test/refactoring change, but if it’s unclear feel free to say “Release Note: no visible change” or “Release Note: None” (we’re not automating anything yet so we don’t need to be too strict about the exact wording)

What do you suppose we should do, if anything, about PRs that we also cherry-pick into the release? Which one of the two (or both of them?) should carry the new annotation?

For PRs that we plan to cherry pick, the release notes should be included in both versions of the commit. They’ll often be documented in both places (this week’s first 1.2 alpha won’t include things that were cherry-picked into release-1.1 during its beta period, but future alphas will include things that were cherry-picked into future 1.1.x patch releases).