Release How To

A release on GitHub represents a point in time in the code history. More specifically, a release is essentially a pointer to a commit in the repository's history. In order to create a release, you will need to tag the commit that finalizes the release. This can be done by

git tag -a v1.2.3 -m "short description"

while HEAD is on said commit. Once this is done, simply push the tag to remote using

git push origin v1.2.3

This will make the tag appear on your remote (note that your GitHub remote might not be called origin). If you want to push all your local tags (not necessarily recommended if you work a lot with them) use

git push --tags

Once the tag is pushed to GitHub, go to the releases tab (just above the language bar in the code section of the repository), and create a new release. There you can give the release's description, a name for it, and link the tag you just pushed to GitHub.

Et voilà, you just created a release.

Note that it should be preferred to only tag commits on master for releases. This is because commands that modify the history of the repository can delete commits and replace them with other ones. Since master is usually branch protected this cannot happen there. For instance, suppose you tag the last commit of a PR for a release, but then rebase-merge onto master once the PR is completed and delete the merged branch, the actual commit you tagged will no longer exist. This is not desired.

Using Releases

Releases can then be used on GitHub to download the code as it was at the time of the release. Moreover, you will be able to locally checkout to that state using

git checkout v1.2.3