Summary

Release the right way

Version

Your releases must be versioned: don’t go custom and simply follow the standard Semantic Versioning 2.0.0. Basically, your versions should of the form x.y.z, where:

  • x defines a major release
  • y a minor one
  • z a patch

When you want to release a new version, determine what is the purpose of your release: is it a bug-fix one, adding some new features, or changing a lot your project with some breaking changes? Depending on that, increase the major, minor or patch part of your version.

Tag

Tag your release on your git repository. This will make it easy to navigate from one release to another and it will automatically create a new release on github, allowing people to download tarball of each release.

Update your CHANGELOG

The changelog is an important part and most people forget about it (including me for a long time). But this file is really important: it is really useful for people upgrading your library and willing to know what has changed. These people are your project users, take care of them :) It also helps you to know what has changed from one version to another without going through the git diff for hours when you are debugging.

Branches

On my libraries, I usually have the main master branch on which I push all releases. This is a good start, but this has some downsides I am currently facing: you can’t fix older versions and you can’t have multiple long time support versions at once.

From my observations, other libraries deal with it differently by having multiple branches, one per major release (or eventually minor release, though rarer). Then, you can easily push patch on these versions by pushing on the corresponding branch and you can keep master as the latest available release. I really like that approach and I plan to use it for my projects in the future. It is also very easy to apply that approach even though you did not use it at first: you can simply create branch from older commits and you are done.