Version Control Procedures¶
Abstract
This chapter explains the version control procedure enforced by the punch team and tools.
Overview¶
The overall principles of PunchPlatform configuration management are explained in version control, to be read first.
For clarity this chapter provides some insight on the use of the version control git tool. We strongly recommend the reading and understanding of git concepts and commands, refer to the Git documentation
Creating Issues¶
Punch issues are tracked on the thales gitlab. They are visible to all. Issues are our primary work tool and our official mean to efficiently provide visibility to our users.
Warning
We do not use issues to keep track of new ideas, to share specification, to discuss. Nor do we consider the issue tracking the developper private tool to organise its own work. Developpers have tons of other means to organise their work. Instead we enfore that ou issue base is a concise, trustable database to be used by users to keep track of the progress and by the support team to manage issues or new feature requests.
- Issues are typed as : bug, feature, enhancement or internal task.
- Bug, feature, enhancement automatically appear in the minor or major release notes.
- Issues are created only by the punch support team members and by the punch development team leader.
- The issue title is always in english, concise and clear, with no capital letters.
- The description for internal can contain french explanation.
- Issues do not contain sensitive project information.
The punch support team manages a Jira HelpDesk portal with their own support issues. Whenever needed these issues are linked to a gitlab issue.
Git concepts¶
git tags¶
Tags are used to mark/identify a past status in a git repository. In PunchPlatform configuration management tags are use to unambiguously refer to a precise release. For example tag '5.6.0'.
Note
a tag stores not only the current state of all files in the filesystem, but also the state of the list of all successive changes that have been made previously (the 'git log') to arrive at this point.
git branches¶
A branch is a working space that is used by one or several users to commit new changes. It can be seen as a 'floating tag' that is automatically updated each time one of the team members pushes a modification to it. This way, one of the team member can easily retrieve the "last status" of this working space.
In Punch team daily work, the following branches are used :
- major release branch. (e.g. '6.1'). These are the branches that hold the latest planned corresponding release. If you compile it or check the version number in the pom.xml files you will get (say) 6.1.4-SNAPSHOT. It means that branch will soon result in a new minor 6.1.4 release.
- feature development branch (e.g. '938-new-security-authent'). These branches are temporary work space for one or more developers working on the same feature. There is no stability constraint on this versions, except if mutually decided by the co-workers using the branch
- local workspace. IMPORTANT : Because of its distributed nature, any developer work space is in itself an 'implicit' branch separated from the workspaces of other developer computers (even tough it has the same git branch name as on other computers). To allow merging of multiple people work, the team git server is used as a storage space into which common work reference is stored. Each developer has to merge/test on his computer the work of the team with his new local changes, and then update the team git server with the result.
Important
There are no global new release branch like a 6.x. If we work on a new release it will be directly named (say) 7.0 and generate a 7.0-SNAPSHOT release the time it is consolidated.
git merge¶
Action of bringing into the working git branch, some changes coming from an other branch, or from any repository state (tag) that includes changes not yet imported in your working branch state.
When merging, git tries to find which "common" version existed in the past (git log) of YOUR branch and the past of the imported branch or tag. Then git tries to determine if changes made since this command on your branch and the imported context can be merged automatically (for example, changes made on different sections of the same file). If not, the user will have to manually analyze this changes to decide what the final 'merged' version of the file should look like.
Version Control Procedures¶
New Feature¶
Why Do That ?¶
- I have to develop a new feature.
- I am a member of the punch development team allowed to integrate features in the coming major release.
- Two major releases are currently maintained with non-frozen feature scope : 5.7, and 6.1
- The team designers have agreed that this feature can and must be developed so as to be compatible with both releases.
Procedure¶
- Request the creation of a feature issue to the punch dev team leader.
- Use the gitlab issue page to automatically create your feature branch. It will be correctly named. Make sure you reviewed with the punch team leadeer what is your starting branch.
- Clone the development repository pp-punch and checkout that branch
git clone https://gitlab.thalesdigital.io/punch/product/pp-punch.git
- Create a feature branch to work independently on common branch, in order to avoid its unstabilization :
git checkout 819-my-great-new-feature
- (Repeatedly) do some changes on files, and commit and secure your changes by storing them on the team git server :
git add <files....>
git commit -m "#8129 implement this and that"
git push origin 819-my-great-new-feature
# Say you started from 6.1
git checkout 6.1
# to retrieve last changes of the team from the team git server
git pull origin 6.1
# git checkout 5x-pp6787-my-new-feature
git checkout 819-my-great-new-feature
git merge 6.1
# resolve any conflicts
git mergetool
git commit -m "#819 merged latest 6.1"
# And, after retesting stability of the integrated version
git push origin 819-my-great-new-feature
When you are done submit a merge request. Make sure you merged with the latest starting point as just explained.
Non Urgent Fix¶
Why Do That ?¶
- You are from the support team
- A bug has been diagnosed on version Dave 6.0.2, which is deployed at a customer site
- The last stable version of Dave is 6.0.4 (in 6.0). There is already a 6.1 release.
- No migration issue is identified in the release notes preventing a migration from 6.0.2 to 6.0.4 requiring change in customer site configuration. The Punch maintenance team therefore decides to build the fix to be compatible with the major 6.0 release.
- The bug is not of critical nature. The support team decides to fixe the issue in the next 6.0.5 minor release.
Procedure¶
- Clone the pp-punch repository and place yourself in the last stable state of the 6.0 branch
- Request a github issue and get the reference to the fixe branch
git checkout 978-syslock-ssl-minor-configuration-issue
git pull origin 978-syslock-ssl-minor-configuration-issue
- Generate the version and reproduce the bug with it
- Develop the bug fix in your branch by (repeatedly) do some
changes on files, and commit and secure your changes by storing them
on the team git server :
```sh
git add <files....>
git commit -m "#978 fixed new configuration variant"
git push origin 978-syslock-ssl-minor-configuration-issue
Once done, wait or check with the punch dev team you fix is ok, unit and integration- tested. The dev team will notify you when your fixe will be merged back in the latest 6.0 minor release.
Hot Fix¶
Why Do That ?¶
The context is the same as for [Minor Fix], except that the support and customer teams agreed to build an urgent dedicated branch and leave for later the integration into the next minor or major releases.
Warning
This is of course rare, and an extremally bad idea as it leaves per customer branch. It clearly is only an urgent procedure only.
git fetch origin --tags
git checkout DAVE-6.0.2
git checkout -b urgent-customer1-hot-fix
Once done and after having solved the customer issue get in touch with the dev team leader so that that branch is integrated in the latest minor release of the corresponding branch.
The customer and punch support team agree on a strategy to converge as soon as possible so that the customer site does not stay on such hot fix branch.
Having Fun Developping a Feature¶
Why Do That ?¶
- I want to prototype/develop a feature on top of the latest punch release
- I am (not yet?) a member of punch development team.
Procedure¶
git clone https://gitlab.thalesdigital.io/punch/product/pp-punch.git
git checkout -b my-crazy-new-feature
Releasing a new minor release¶
Only the punch dev team lead is doing that. Check with him ! the procedure is fully documented.