Legacy Branching & Releasing
The legacy QuarterCode branching & release model is a derivation of the nvie branching model and is used in every public QuarterCode project.
This page offers an explanation of the model for developers (Complete Branching & Release Model), as well as a compacted one for users who are interested in the release process (Compact Release Model).
Complete Branching & Release Model
First of all, there are two main branches with an infinite lifetime: master and develop. Active development is done on the develop branch, the master branch is reserved for releases.
Small feature are generally directly added to the develop branch. This branch must always be compilable! If you want to add a feature to the develop branch, you have to complete it before commiting. Because of that, adding things directly to the develop branch is only recommended for very small features and bugfixes.
If you want to create a larger feature, you should consider creating a new feature branch from develop. Feature branches should be named like feature/<feature>. Every letter should be lower-case, hyphen are allowed (example: feature/some-amazing-feature). On this branch, you can do whatever you want, nobody expects anything fully usable or even compilable on a feature branch. You can develop your feature and commit every change, even if you break the program with a new commit (heavy commitment). When you're done with your feature, you can simply merge your feature branch into the develop branch. Of course, you can also throw your feature away by simply deleting the feature branch without merging it into develop.
Cycles and Versions
Cycles are basically groups of releases which all have the same features. For example, the releases 1.0.0-ALPHA.1, 1.0.0-BETA.4, 1.0.0, 1.0.1 and 1.0.2 all belong to the cycle 1.0.x.
The first published version of a new cycle is the 1.0.0-ALPHA.1. It's like a first impression of the new version. There can be multiple alphas until the first beta 1.0.0-BETA.1 comes out. All the main features of the new version should be in there. Of course, the alpha and beta stages can be skipped completely if there are not many large changes.
After some beta releases and when the feature work is done, the first release 1.0.0 is published. Sooner or later bugs will pop up or small changes need to be made. When the bugs are fixed, a hotfix is published (e.g. 1.0.1 or 1.0.2). Such hotfixes don't have anything to do with the next cycle (e.g. 1.2.x) and there won't be any more as soon as the first release of the next cycle comes out (e.g. 1.2.0).
During the development of a new version, the develop branch code holds the version of the next cycle the format <version>-SNAPSHOT (e.g. 1.0.0-SNAPSHOT). For creating an alpha or beta, the version is simply bumped to <version>-ALPHA.x/<version>-BETA.x, the change is committed and the version is bumped back to <version>-SNAPSHOT. For publishing a release, a new branch release/<version> (e.g. release/1.0.0) is created and the version is bumped to just <version> (e.g. 1.0.0) on that branch. After that, the release branch is merged into master and deleted afterwards.
For creating hotfixes, a new hotfix/<version> branch is created from master (e.g. hotfix/1.0.1 or hotfix/1.0.2). The bugs can be fixed there. When the work is done, the branch is merged back into master as well as into develop.
Branching Model Graph
Here's a slightly simplified ASCII graph demonstrating the branching model (we ignore the release branches for a smaller graph):
master hotfixes releases develop ------ features ------
|
| initial branching
o------------------------------------> o
| | for future release
| o-----------------------> o
| | |
| o o
| | for next r. |
| o--------------> o o
| | | |
| o o o
| Version: | | |
| Snap -> Alpha -> Snap #o# o o
| | | |
| o o o
| | complete | |
| o <--------------o o
| | |
| o o
| | cool feature |
| o--------------> o o
| Version: | | |
| Snap -> Beta -> Snap #o# o o
| | not so cool |
| o o
| | |
| o--------------> o o
| | | |
| o o o
| | | |
| o o o
| | | |
| o <--------------o o
| release over release branch | |
release o <----------------------#o# <---------o o
1.0.0 | Change Version | |
| o o
| | |
| o o
| Hotfix | |
o---------> o o o
| | | |
| o o <-----------------------o
| | |
release o <---------o o
1.0.1 | |
| o
| |
V V
Compact Release Model
Every new cycle (e.g. 1.0.x) starts with an alpha. The alpha is very experimental, but it is "stable" (e.g. 1.0.0-ALPHA.1). If you want to take an early look on a new version, you should try the alpha. The beta is the next stage of development. The major features should be implemented there (e.g. 1.0.0-BETA.1). There can easily be multiple alphas and betas. They are separated by the last number of the qualifier (e.g. 01, 02 ...). There can also be no alphas or betas if they are simply not required.
When the work on the new cycle is done, the first release of the new version is published (e.g. 1.0.0). However, sooner or later bugs will pop up or small changes need to be made. When the bugs are fixed, a hotfix is published (e.g. 1.0.1 or 1.0.2). Such hotfixes don't have anything to do with the next cycle (e.g. 1.1.x) and there won't be any more as soon as the first release of the next cycle comes out (e.g. 1.1.0).