-
Notifications
You must be signed in to change notification settings - Fork 76
Maintainers README
Here we introduce the conventions between everybody with a write access to the repository.
Changelogs are written to CHANGELOG.md.
Changelogs are generated using GitHub Changelog Generator to give the big picture of all changes, but then extensively edited to match the desired look. As an example of what is the desired look, compare the outputs of the minimal example for github-changelog-generator given in the note below and git tag example from Tags section.
Changelogs are generated before tagging, since you will supply release notes as a tag's annotation. Therefore --future-release is used in the note below.
Note: do not just run github-changelog-generator. Firstly, it will automatically rewrite CHANGELOG. Instead, you will want to append the changelog manually after editing it. Secondly, it'll give you a lot of unneded information. Make sure to familiarize yourself with program's options. Minimal example: github_changelog_generator --since-tag v0.2.7 --future-release v0.2.8 --release-branch master.
Tags are done on any branch.
Annotated and GPG-signed tags (see git-tag(1)) are used. They are in form vA.B.C, where A,B,C are numbers 0-99 (example: v0.2.7).
Tags follow semver in general, but there are no strict rules. Listen to your heart.
Every tag contains a changelog as its annotation. See Changelogs and Releases for the details (example: git tag -l -n99 v0.2.8).
Note: while pushing new tags, remember not to do git push --tags as it pushes all tags. Always push only the newest tag (example: git push v0.2.8).
Releases are done only on master branch.
When we are ready to release the next iteration, the commit that bumps the VERSION file is tagged (example: git show v0.2.8).
Note: VERSION bump is the last commit in current iteration. Every next commit is included in the next iteration. Therefore make sure to commit all necessary changes before the bump.
Note: if there's no VERSION file in the root of the source code tree, this means a transition onto CMake has happened. Bump the numbers in the main CMakeLists.txt instead.
GitHub's release (e.g. release made through GitHub's UI or API) is created right after the tag is pushed.
Every release contains a changelog. See Changelogs for the details.