version control
Version-control is the SCM discipline of identifying and persistently recording the configuration of a software product with its source artifacts at discrete points in time and on particular branches for the purposes of systematically controlling changes and maintaining the integrity and traceability throughout the life-cycle of the software product and its source artifacts.
-
Who made a particular change and when?
-
Which changes happended at all between date XXX and YYY?
-
When do we merge branches and in which direction?
-
Should we create a branch — and when?
-
Who is able to read the source artifacts and who can commit changes?
For version-control you should follow these best-practices:
All your work on source-code, configurations, documentation and any other source artifact shall be strictly put into the version-control-system (VCS) of your project. Frequently commit your changes and push them to the VCS to avoid loosing any valueable work. Your local disc may crash or get corrupted and also you may get sick unplanned and your team should be able to take over. If your work is always available on according feature branches, you and your team are prepared for the unexpected. A proper backup strategy has to be applied to the VCS on the server-side to ensure the valuable data can not be lost.
Follow a well-defined strategy for branching and merging your source artifacts. Balance flexibility for development with stability during maintenance. However, keep the number of parallel branches at a minimum.
Simply using a version control system (VCS) for managing your source artifacts is not sufficient. You also have to follow a well-defined strategy for creating branches and merging them. A typical VCS is generic and will not guide you or restrict wrong merging directions.
The overall goal of a version-control strategy is to support the creation of high quality releases.
We strongly recommend to stick to the following rules:
-
There is one single default branch that always represents the latest stable development line. We logically call it mainline and technically it is typically called
masterormain(at least in git). -
This mainline shall always contain a working state that allows to build a working release (see continuous-integration).
-
Releases shall be created frequently (according to sprint or increment planning or even better automated via continuous-deployment) from the mainline.
-
Avoid maintaining older released whenever possible to reduce complexity. However, if you have to do, use according release-branches that you frequently merge back to the branch they have been created from and from there further to the mainline to ensure already fixed bugs never occur again in later releases.
For each change the developer(s) create feature-branches from the latest mainline. Here, they can work on their feature (story) in isolation of other features and changes. A feature should be small and therefore the feature branch can be quickly merged and does not exist for very long (days not years). When the feature is complete, the developer(s) ensure(s) the feature branch is up-to-date via upstream-merging with the mainline. Further, specific quality checks defined by the definition of done (DoD) have to be met for the feature to be complete. Then a pull- or merge-request is created from the feature branch. After a quality assurance and review-process the pull-/merge-request gets merged onto the mainline and the feature is complete.
A common branching- and merging strategy has been published as git-flow.
While it contains several best practices it also contains aspects that we consider as an anti-pattern:
The concept of maintaining a development and a master branch in the way suggested by git-flow is flawed (produces severe problems whith release branching) and adds pointless complexity and maintenance.
Some problems are also summarized here.
As tools like github or gitlab have been established, we strongly encourage to use them and follow their more advanced fork and merge workflows.
Therefore, avoid being misslead by git-flow as it has initially been defined.
Create an immutable tag for every release.
Create a tag for every release of your software.
Always tag the complete mainline of your version-control-system so everything including documentation is recorded together.
Follow a clear and simple naming convention for your tags (e.g. release/«version» or just «version»).
Tags shall be treated as immutable and are therefore never modified (or deleted and recreated) afterwards.
If something went wrong with your release, create a new one with a new version and a new tag.
You should never commit your build artifacts or third-party libraries into your version-control-system. Instead deploy such artifacts to the artifact-repository.
This documentation is licensed under the Creative Commons License (Attribution-NoDerivatives 4.0 International).
