IAS git branching
We adopt the Git Flow branching model suggested by Vincent Driessen:
- the master branch contains code ready to go on production
- the develop branch contains the code of the features that have been developed but not yet put in production
- the feature branches are used to develop new features, when the feature is finished the branch is closed and merged to develop. They follow the name convention: feature/my_feature_name
- the hotfix or bugfix branches are used to work on hotfixes and bugfixes respectively. Once finished they are merged to BOTH develop and master
- the release branches are used to make final adjustments when putting code in production, from develop branch to master branch
In order to facilitate this, we use the git flow tool. To understand how to use git flow (a.k.a the workflow of git flow) check the cheatsheet created by Daniel Kummer
We create release following the git flow schema. The name of each release is prepended by a 'v' followed by three numbers, like v1.3.7. All releases started with a 0 are those not yet ready to go in production. For them we do not create a branch. Release v1.0.0 is intended to be usable in control room even if not complete. For such releases there will be a branch associated.
The release numbering schema does not follow the classic semantic versioning schema because the ¦AS is composed of many repositories. Managing releases across many repository is a known problem and there aremany articles in the web that mainly suggests to
- avoid multiple repositories in favor of a big monolithic repository; eventually splitting into many read-only repositories with tools like splitsh
- use git submodules
Both approaches have pros and cons as you can read in Rotislav Vitek´s blog.
The numbering of each of the repository of the ¦AS is composed of 3 numbers: INTEGRATION, MAJOR, MINOR, like v1.23.5, with the following meaning
- INTEGRATION: it is increased whenever a new multi-repository release is created
- MAJOR: incremented when there are incompatible API changes
- MINOR: when adding backwards-compatible functionalities and bug fixes
The INTEGRATION is used to make a integrated release of the whole ¦AS project. For example to run version a of the ¦AS, you need to checkout and build va.0.0 of all the repositories.
MAJOR and MINOR changes independently for each repository depending on the functionalities and bug fixes implemented: it they are backwards-compatible only the MINOR number is incremented otherwise the MAJOR is incremented.
Being the MINOR releases backwards-compatible, it would be possible to successfully integrate repositories with release numbers like va.0.b. For example, we can integrate version v5.0.0 of the web server with version v5.0.15 of the core as they have the same INTEGRATION number and no backwards-incompatible changes. Note that backwards-compatibility imply changes in the API and in the interfaces between the subsystems.
Mixing MAJOR releases could or could not work. If the changes are only in the API internal to a repository without affecting the interface would allow to mix otherwise not so it must judged case by case.
As a general rule to build multiple repository releases ensure a) to use the same INTEGRATION number of each repository with MAJOR=0 and b) get the biggest MINOR number available for each repository. If needed a script to automatically checkout and build t¦AS compatible sources from all the repositories can be provided.
There are of course many other possible solutions to this problem: we try to keep a useful schema naming convention Reducing the workload. As such, if needed we will change the naming schema if we will find a valid reason to do so in the future.
