It has been some time since we started development of our Symfony based ecommerce framework as an open source project. Before, all of us were used to working with proprietary software where releasing new versions only involved publishing a new git (or SVN) tag. But times have changed and our product is now dedicated to helping developers all over the world. Even though we learned about open source development as we went, we knew from the beginning that publishing a newer version of the framework deserved a little bit more attention.
The Checklist
When striving for perfection, we created a checklist for our release process which prevents maintainers from forgetting anything important when releasing a new version of Shopsys Framework. Needless to say, the process is constantly evolving as we verify it in practice during each iteration. Now, let us go through the checklist and briefly describe all the work that needs to be done when a new version is released.
Step 1 – Check TravisCI
Shopsys Framework is developed in monorepo and our internal CI server builds and checks the whole monorepo altogether. Because of that, the functionality of single packages is tested by TravisCI after a feature is merged into the master branch and the monorepo is split. So, the release time is suitable for ensuring that all packages of monorepo work properly on their own, i.e. all projects in our Travis CI have green statuses.
Step 2 – Create new git feature branch
Releasing a new version always requires some changes in the code, so a new git branch has to be created. The standard convention is that the branch be prefixed with rc- (as in “release candidate”) and followed with the name of the upcoming version, e.g. rc-v7.0.0-alpha2.
Step 3 – Prevent others from merging into master
It is important to inform everyone in the team that the release process is in progress, and therefore merging new features into the master branch is temporarily disallowed. Usually, we put the information on our team slack channel and also write a warning message on the scrum whiteboard in our office.
Step 4 – Examine composer dependencies
In our composer.json, we use caret version range for a definition of our external dependencies. But there are a few exceptions to this rule (which should be described in a commit message). The release process is a suitable time for examining these non-standard dependencies and defining them the standard way if possible, e.g. new version of given package including important bug fix is available. Also, all forked repositories should be checked to see if their usage is still relevant or whether it is possible to use the original package.
Step 5 – Update translations
Since Shopsys Framework supports multiple languages, all translatable texts are exported into files for translations using phing targets. Sometimes a developer forgets to fill the corresponding translation for their new strings and, again, the release process is a suitable time for adding any forgotten translations into translation files, as well as performing any other translations corrections.
Step 6 – Update changelog and upgrading notes
Changelog and upgrading notes are maintained continuously, and new entries are added into “Unreleased” section during a regular development process. Before releasing a new version, it is important to set the new version number and release date for all unreleased changes.
Step 7 – Change dependencies in monorepo packages
To provide the functionality of the whole monorepo ecosystem during development between releases, all the packages are dependent on each other’s master versions. But in the released version, the dependencies must be changed to the upcoming version number. As Shopsys Framework is in the alpha stage now, each change can cause BC breaks so the dependencies are set to the concrete version numbers. This prevents application from unwanted breaks during the composer update.
Step 8 – Verify functionality
By building the application locally and on the CI server, we verify that everything works well after all the changes are done.
Step 9 – Let your work be reviewed
Our standard development process includes a code review that takes place in the pull request on GitHub. Releasing new versions is no exception.
Step 10 – Let your work be tested
Despite the fact that we do write automated tests, the release is so important to us that in this step we rely on a human tester to manually test the application.
Step 11 – Check the release date
Sometimes the release process can take a few days so it vital that we check the release date in the changelog just before the new version is actually released.
Step 12 – Merge the feature branch into master
We try to keep our git history as readable as possible. We believe that writing descriptive commit messages even for changes during the release process, rebasing feature branches on master branch, and creating merge commits serves to enhance clarity.
Step 13 – Create and push a new git tag
After the feature branch is merged into the master, it is necessary to mark the merge commit as the new version of our framework. This is done simply by using a git tag.
git tag v7.0.0-aplha2 && git push — tags
Step 14 – Check the new release
This is the step when we verify that everything works well for the last time, i.e. check all Travis builds as well as builds on internal CI, check whether the new version is available on packagist, and double-check the installation of the released version by manually following installation guides.
Step 15 – Change the dependencies in monorepo packages back
After the new version is released, we revert the dependencies of monorepo packages to ensure that new unreleased versions are capable of working together properly.
Step 16 – Add release notes on GitHub
Each good release on GitHub needs proper release notes. Luckily for us, we write nice notes into our changelog so we just copy and paste the information from there.
Step 17 – Let people know about the new release
A brief message summarizing the new version should be written in Shopsys Framework Slack.
Step 18 – Celebrate the new release
Releasing new version is always a good cause for a little celebration!
Conclusion
Even though it seems that most of these steps are really simple, it is very useful to have them all written down so even a novice in our team can handle the whole process when following the instructions. We also include important notes about unusual situations that can occur during the process so nobody else is unpleasantly surprised when something weird happens.
The good thing about keeping the checklist is that when you really put it all down on paper, you almost immediately spot steps that can be improved (or, even better, automated). As mentioned before, our release checklist keeps changing and we are always looking for ways to optimize these steps in the following weeks and months. Do you see any room for improvement of our process? Let us know in the comments below or create a new issue on our GitHub. It will likely be interesting to see how the process evolves over time.
