Avoid tagging commits in the
Release branches should have annotated tags and a CHANGELOG.md.
The steps below detail creation of a brand new 1.0.0 release. Some steps would be omitted for minor releases.
Creating an initial release
Update references to version numbers in relevant documentation to the new version you intend to release.
git checkout master vim docs/installation.adoc git add docs/installation.adoc git commit git push
Release branches have names of the form
release/N.x, where N is the major
x is a literal — not a placeholder).
git checkout -b release/1.x master
Update CHANGELOG and version
vim CHANGELOG.md # Add/update CHANGELOG entry for the new version git add CHANGELOG.md echo 1.0.0 > version.txt git add -f version.txt git commit
An initial release would be tagged as follows:
git tag -a v1.0.0 -m ''
Push branch and tag
# push the branch git push origin release/1.x # push the tag git push origin v1.0.0
Edit tagged release description on GitHub
Navigate to the Releases page;
Edit the tag that was just pushed;
Fill the tag’s description with data from the corresponding
CHANGELOGentries of the same tag version;
Publish the release.
Creating a new release
Maintaining a release branch involves cherry-picking hotfixes and
similar commits from the
master branch, while following the rules for
The steps below will show the release of version 1.0.1.
Add desired changes
Cherry-pick the appropriate commits into the appropriate
To see what commits are in
master that are not in the release branch, you
can observe the lines starting with
git cherry -v release/1.x master
It is often useful to pick a range of commits. For example:
git checkout release/0.x git cherry-pick a57b36f^..e23352c
If there are merge commits in this range, this will not work. Instead, try:
git checkout release/0.x git cherry release/0.x master | grep '^+ ' | cut -c 3-9 | \ while read commit; do git cherry-pick $commit; done
From here, you can follow the steps for an initial release, starting with Update CHANGELOG and version.