Skip to content

Document guidelines for writing release notes #685

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 6, 2025
Merged

Document guidelines for writing release notes #685

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ Seen something outdated or plain wrong? Spotted a typo somewhere? Think somethin
- [**Maintainer's guide**](#maintainers-guide)
- [Versioning](#versioning)
- [Release process](#release-process)
- [Release notes](#release-notes)


## Contributor's guide
Expand Down Expand Up @@ -409,6 +410,56 @@ Content changes, such as adding a note, replacing an image, or translating the d
1. Tick the _Copyright_ box and click _Share_.
1. Announce the release [on Reddit](https://www.reddit.com/r/Anki/search?q=ultimate%20geography&restrict_sr=1), with links to the release notes, to the upgrade instructions, and to the _Discussions_ and _Issues_ pages.

### Release notes

The purpose of release notes is to give existing users:

- an overview of what's changed in the deck from one version to the next;
- specific instructions on how to upgrade, if any;
- news on the project, future developments, etc.

The goal is to avoid users: feeling confused when discovering content changes as they review; missing some subtle changes (e.g. spelling, new supplementary information, etc.); or not finding out about changes for a long time because they happened in cards that they won't see again for a while.

We also don't want users who are interested in staying up to date with changes to have to subscribe to PRs or hunt for changes in git diffs.

With these goals in mind, it's important to write release notes that are **concise** yet **precise**, **well structured**, and **easy to read**. Keeping the structure, wording, emojis, etc. **consistent** across releases is also important and can be achieved by looking at and getting inspiration from past release notes.

The recommended structure, which can of course be tweaked and expanded as needed, is as follows:

1. Short introduction to summarise the most significant changes and/or give updates on the projet _(optional)_.
2. Concise upgrade instructions, typically pointing to detailled procedures in the README and wiki.
3. New translations, if any (including language code).
4. New notes, if any, with links to Wikipedia and optionally justification on why those notes were added (e.g. new/changed inclusion criteria)
5. Changes to country names, capitals and supplementary info.
6. Changes to maps and flags.
7. Other changes, for instance to the structure of the deck (tags, description, etc.), the documentation (when significant), or the BrainBrew recipes and development tool chain (if relevant to power users).
8. Contributors (at least new contributors) _(optional)_

Here are som additional guidelines:

- If the upgrade is non-trivial, make sure to grab users' attention with bold text, emojis, etc. at the top of the release notes.
- Don't write release notes from a contributor's point of view (i.e. one bullet point per pull request/commit/issue), but from a user's point of view (i.e. one bullet point per meaningful change). Indeed, it's common for one change to span multiple pull requests (e.g. new translation followed by various corrections), and it sometimes happens that multiple changes are done with a single pull request.
- Be as specific as possible, for instance by mentioning the country name of the affected note, except when a lot of notes are affected by similar minor changes (like when a lot of typos/mistranslations are fixed in a specific language).
- Always link to relevant issues and pull requests with the `#` syntax.
- Mention contributors for new translations and other major changes.
- Specify language code(s) for changes that concern only few translations of the deck — e.g. [EN]; [DE, ES, FR]
- Add emojis but only for _notable_ changes, typically:
- 🎉 for new translations,
- 🗑️ for content removals
- 👉 for factual changes (e.g. official change of flag, new alternative name, more detailed supplementary info, etc.)
- ⛑️ for significant corrections (typos, unclear wording, mistranslations, wrong supplementary info, etc.)
- ✨, 🌟, or any other emoji as needed.
- Within each section, respect the following order:
1. Notable changes first (i.e. those with emojis)
2. Then by type, in this order: highlights 🎉, removals 🗑️, factual changes 👉, corrections ⛑️
3. Then by number of translations impacted (i.e. no language code first, then by decreasing number of language codes)
4. Then by significance.
- Use bold, notably to emphasize country and capitals names.
- In the case of a correction or change of spelling, emphasize only the new name.
- When a change concerns a capital, emphasize only the capital name, not the country name.
- When a country/capital name changes in a translated deck, specify the English name in parens.
- Add links to documentation, Wikipedia, etc. where relevant.

[ref129]: https://github.com/anki-geo/ultimate-geography/issues/129
[ref137]: https://github.com/anki-geo/ultimate-geography/issues/137
[ref157]: https://github.com/anki-geo/ultimate-geography/pull/157#issuecomment-549143860
Expand Down