Here is a list of things that would be helpful to document in making a release:
1. The changelog PR
This should be consistently named to reflect the version number:
2. Add instructions on how to write changelog.
This should be a bulleted list in the style of commit messages. Keep the bulleted phrases short. Always start with a verb for each bullet. Try to use the same verbs as much as possible. Fix and Add should be the most common. Other acceptable verbs include rename, remove, extend. Sort the bullets by verb. Always list Fix first, then Add. Ideally, each of the bullets corresponds to an issue/PR. However, often this leads to too repetitive of a list. It is more important that the list be brief. The overarching principle is that the list should be understandable and useful to the people who develop the code. See AMDC-Firmware as examples of acceptable changelog entries:
3. Explain that release notes should match the CHANGELOG.md entry for this release
4. Add a step to the release instructions to go into ReadTheDocs and activate the documentation for each major release
We don't think this is necessary for minor releases. This allows people to select specific releases in readthedocs, like v1.0.0 or v1.1.0
To get here in ReadTheDocs go to eMach --> Versions
5. Add a discussion about how we are tracking which issues/PRs are going into a specific release.
Here is a list of things that would be helpful to document in making a release:
1. The changelog PR
This should be consistently named to reflect the version number:
2. Add instructions on how to write changelog.
This should be a bulleted list in the style of commit messages. Keep the bulleted phrases short. Always start with a verb for each bullet. Try to use the same verbs as much as possible.
FixandAddshould be the most common. Other acceptable verbs includerename,remove,extend. Sort the bullets by verb. Always listFixfirst, thenAdd. Ideally, each of the bullets corresponds to an issue/PR. However, often this leads to too repetitive of a list. It is more important that the list be brief. The overarching principle is that the list should be understandable and useful to the people who develop the code. See AMDC-Firmware as examples of acceptable changelog entries:3. Explain that release notes should match the CHANGELOG.md entry for this release
4. Add a step to the release instructions to go into ReadTheDocs and activate the documentation for each major release
We don't think this is necessary for minor releases. This allows people to select specific releases in readthedocs, like
v1.0.0orv1.1.0To get here in ReadTheDocs go to
eMach-->Versions5. Add a discussion about how we are tracking which issues/PRs are going into a specific release.