To ensure - as much as possible - the quality and correctness of our code, and to enable many contributors to work on our apps at the same time without getting in each other's way we use a modified version of the GitFlow work flow by Vincent Driessen.
We call this work flow SuperFlow.
Below you will find Vincent's original diagram adapted and extended corresponding to SuperFlow followed by an explanation of the various concepts and steps involved.
Legend:
- Purple bubble: start of a release or hot fix branch
- Yellow bubble: pre-release tag
- Blue bubble: release tag
- Green arrow: merge that requires review
develop is our main branch. It corresponds with the current work-in-progress state of the app, that we deal with most often as developers.
develop is a protected branch and no commits can be pushed to it directly. The only way to add features, fix bugs, and make other changes is through pull requests that pass review and automated tests. For more details, see our pull request etiquette.
master represents the stable and publicly released status of the app. Each commit on master represents a specific and unique public build.
master is a protected branch and no commits can be pushed to it directly. The only way to push to master is by going through our release flow as explained below.
Feature branches are branches created by developers based on develop which are used create new features, fix bugs, and make other changes to the app.
Unless explicitly stated otherwise, only the feature branch's creator may push changes to it. Other developers may always create pull requests to submit changes to the branch.
When a feature or change is done, it is merged into develop via a reviewed and tested pull request. This merge can happen using a squash for simple changes, and or a merge commit otherwise.
Release branches are one of the only two ways of creating a new public release. They are branched off of develop and stay alive until the corresponding version is released.
The only commits that may be pushed directly to release branches are version and build number increments. All other changes must be applied using pull requests from release bug fix branches.
After incrementing version and/or build numbers, pre-release tags can be created on the release branch to trigger a pre-release build for testing.
Once work on a release branch is completed and sufficiently tested, it will be merged back into master and develop (both are required) using merge commits through reviewed pull requests.
Release bug fix branches are branched off of a release branch if bugs are found during testing of a pre-release build. The bug is fixed on that branch, after which it is merged or squashed back into the release branch using a reviewed pull request.
Unless explicitly stated otherwise, only the bug fix branch's creator may push changes to it. Other developers may always create pull requests to submit changes to the branch.
Hot fix branches are branched off of master in the case of a critical bug in a production build. They are the second of two ways of creating a new public release.
In most cases the bug can be fixed directly on the branch and does not require pull requests.
Unless explicitly stated otherwise, only the hot fix branch's creator may push changes to it. Other developers may always create pull requests to submit changes to the branch.
After incrementing version and/or build numbers, pre-release tags can be created on the hot fix branch to trigger a pre-release build for testing.
Once work on a hot fix branch is completed and sufficiently tested, it will be merged back into master and develop (both are required) using merge commits through reviewed pull requests.
The above explanations of SuperFlow are not only sub-set of allowed operations, but are in fact exhaustive. This means that there are no other valid ways to create releases, than outlined above.
In summary:
- Release and hot fix branches are two only two ways of creating new public releases.
- Release and hot fix branches branch from
developandmasterrespectively. - Release and hot fix branches are always merged into both
masteranddevelopon completion. This merge is always performed using a non-fast-forward, non-squashed merge commit.
Our apps follows the following versioning scheme:
major.minor[.maintenance]
- The
majorcomponent is changed only upon special considerations. - The
minorcomponent is incremented by one as the first commit of every release branch (and in no other case). The same commit also removes themaintenancecomponent. - The
maintenanceis added and incremented by one as the first commit of every hot fix branch (and in no other case).
In addition, there is also the build number which is not visible to the public and only used to distinguish different builds internally. This number is incremented in all the three cases above. In addition it is incremented for any additional pre-release build created.
In essence, the versioning scheme can thus be thought of as:
major.release[.hotfix]
Release tags are our way of marking commits as releases, and trigger appropriate builds.
There are two kinds of release tags.
Pre-release tags are created on release and hot fix branches to create internal test-builds. They have the naming scheme *.*-pre# or *.*.*-pre# respectively. The pre-release number # starts at 1 for each release/hot fix branch, and is incremented for further test builds.
Pre-release tags should ideally be only applied to commits increasing the build number (and version number if appropriate), and may be applied only to commits with unique build numbers, such that each triggered build has such a unique build number.
Pre-release tags have to be marked as pre-release on GitHub.
Public release tags are created on master and correspond to public releases. They have the naming scheme *.* or *.*.* depending on whether the merge commit they are on merges a release or hot fix branch respectively.
Since each commit on master is a merge commit and corresponds to a public release, each of them should have a public release tag.
Public release tags may not be marked as pre-release on GitHub.
Each release tag created on GitHub should have a succinct and clear, yet exhaustive changelog. In the case of pre-release tags, the changelog should include the changes since the previous pre-release of the same release, or the previous release if this is the first pre-release of this release. In the case of release tags, the changelog should include the changes since the previous release, and does not have do include fixes for bugs that were not present in that previous release.