Tips to successfully build your open-source projects #5. Release the right way
Once people start to use your project, you need to make sure you don't break things unexpectedly for them.
More specifically, your users have built their projects around a specific version of yours. You may have great improvements to release, but your users do not want to discover these changes by surprise. Instead, they want to have control over which version of your project to use and when to upgrade to a more recent version.
Versioning
Your releases must be versioned. Versioning allows naming each of your releases, thus making it easy to identify which version of your project should be used.
The standard way to do versioning is to follow the Semantic Versioning 2.0.0 recommendations.
Basically, your versions should of the form MAJOR.MINOR.PATCH . For example, 1.0.0 , 1.4.0 , 1.6.18 , and so on.
The version of a new release will be based on the version of the preceding release, but with either the MAJOR , MINOR or PATCH incremented depending on the changes included in your release. More specifically, you should increment:
- The
MAJORversion when you make breaking changes. That is if upgrading to this version requires adjustments in the integration of your project. For example, removal of some features, changes in parameters or outputs of some APIs, renamed configuration settings, … - The
MINORversion when you add functionality in a backward-compatible manner. That is if upgrading to this version brings meaningful changes without breaking the existing integration of your project. For example, features deprecations, new features not impacting existing features, … - The
PATCHversion when you make backward-compatible bug fixes. This is similar to theMINORversion, but for bug fixes.
One main advantage of this naming convention is that you can maintain multiple major or minor releases in parallel while making it easy for your users to understand how your different releases are connected with one another.
For example, the most recent version of your project could be 4.2.1 , but you know that most of your users are still using an older version, 3.9.12 . If someone finds an important security issue on 3.9.12 , it may be inconvenient for your users to upgrade to 4.2.1 considering the breaking changes. Instead, you can make a new release based on 3.9.12 fixing the security issue, and version this new release as 3.9.13 .
Tagging
Tagging your releases with Git makes it easy to navigate from one release to another. Additionally, Github can automatically create a new release on its UI, allowing people to download a tarball of each release (assuming you open-sourced your project on Github).
CHANGELOG
The changelog is an important part of the release process, but new project owners tend to forget about it (including myself for a long time).
As I mentioned at the beginning of this article, your users do not want to discover changes by surprise. They want to decide when to upgrade to a new version, and they want to understand what they are getting into once they are willing to.
The changelog of your project is an exhaustive summary of all the changes for all the releases of your projects. It details what has changed and what to consider when upgrading to a specific release. Thus, it's something people are looking for when upgrading, or when troubleshooting issues after an upgrade.
Without a changelog, they would have to manually run somegit log or git diff: that's time-consuming and very easy to miss something.
There isn't a standard way to write changelogs. However, keepachangelog.com is a very resource to get started.
The main point is to avoid generating it from your git log or git diff. Instead, you should follow the same advice I gave in my two previous articles, Tips to successfully build your open-source projects #3. Have a sexy README and Tips to successfully build your open-source projects #4. Document your project: understand the needs of the person who will read this changelog.
A good changelog should document each release with the following information:
- Version: What is the version of the release?
- Date: When were the changes released?
- Added: What new features were added in the release?
- Changed: What existing features were modified in the release? How were they modified? What is the impact of these changes?
- Fixed: What bugs have been fixed in the release?
- Deprecated: What existing features do you plan to remove in a future release? What should be used instead?
- Removed: What existing features have been removed in this release? Are there any alternatives?
- Upgrade considerations: Any details to consider when upgrading? Anything in particular to look out for? Any recommendations to handle breaking changes?
As you can see, writing a good changelog can take some time. It might feel like a lot of work, especially after spending efforts writing unit tests and documentation. But it’s worth it: it will help your current users smoothly adopt your most recent improvements!
Branch Management
For my libraries, I usually have the main master branch where I push all releases.
This is a good start, but this has one major downside I am currently facing: you can’t fix older versions and you can’t have multiple Long-Term Support (LTS) versions at once.
Another approach is to maintain multiple branches, one per major release (or eventually minor release) that you want to support. Then, you can easily push patches for these versions by pushing on the corresponding branch, and keep the master branch for the latest available release.
For example, if we take our previous example of a project with the most recent version being 4.2.1 , but most people still using 3.9.12. In this case, you could have dedicated branches for the versions 4.X.X and 3.X.X where you can push new minor and patch releases without affecting other major versions.
Conclusion
Releasing a new version of your project is always exciting: you worked on some improvements and want to deliver them to your users.
However, it's important to take the time to release correctly and to acknowledge that many of your users may not want to upgrade to your latest version as soon as you released it.
Versioning and tagging your releases, documenting them with a changelog, and having good releases branch management are many things to consider in your release process for an open-source project.
Read all my tips to successfully build your open-source projects:
Originally published at https://cylix.github.io on September 9th, 2017.
