Tag & branches policies

I like to dig in github for libraries and other useful components to add in a project I’m working on. I’m much more experienced on Subversion than Git, the trending version control system. Git success is claimed by it’s strong branches features and it’s distributed repositories with push and pull, specially usefull on open source project but, when looking on most open source repositories in github i didn’t see a meaning full use of tag and branches. That’s why I decided to create this article.

I propose here what is, IMHO, a good way to use tag and branches, on a software project context with build/delivery, and maintenances of several release in a software R&D project.

A version control system repository must used for each software product or solution. Several release or maintenance project on the same software should share the same central repository.

The root directory containing all the delivery content is tagged.

At least each delivery to customer or other external teams are tagged. The tag name follows a tag rule name like Apache versioning or Semver (for me, the first digit should be trigger by marketing needs).

Each maintained software release must have a branch created just after it’s offical delivery.

This figure shows an example of branches and tags on a software products built and delivered in several iterations (or Scrum sprints) and then maintained in several version, like when several customer are using differents differents version as operating systems.


  • 1.0.0 to 1.0.4 where delivered to the customer as iteration deliveries, 1.0.3 was not delivered because of a NOGO after customer acceptance review
  • 1.1 release is maintained in a new maintenance branch for a customer guarantee since 1.1.4, while 1.2 released are done on the same branch as 1.1 and 1.0
    • On 1.1 maintenance, after 1.1.5 maintenance release delivery, 3 patches where delivered. 1.1.6 maintenance release includes those patches making them deprecated for 1.1.6 and next 1.1 maintenance release
    • Issues fixed in 1.1 maintenance branches should be merge in 1.x and maybe 1.3.x branches
  • 1.3.x started on a new branch because significant design changes where done (1.x branch can now be used for maintenance for 1.2 maintenance
  • 2.0 start release starts from scratch (avoiding commits and tags on master is an usual practice)

The « dev/ » at the bottom left corner stands for the directory where all the delivery content source files are stored : source code, configuration files, samples,  delivered documentation… You Should have another directory at same level, lets call it « doc/ », where all undelivered elements are stored  : project documents, internal technotes…

I will describe deeper what these directory content in another article. If you can’t wait, you can have the full picture, with much more information like project milestoner, or server environments in the Software R&D Best Practices training.