Policies for Git usage of the Starlink source code repository
This document describes the basic policies and conventions that should be adhered to when committing changes to the Git source code repository. This is a live document and should not be considered as policies set in stone. They may evolve as we become more familiar with git.
- Git treats the first line of a commit message specially. It will be displayed in the shortlog output and in the main gitweb summaries. The first line should succinctly describe the patch. If additional information is required it should be given in the body of the commit following a blank line.
short message here Longer description of the patch in here.
Use git pull --rebase if you are developing in master and updating from the remote. This prevents an unnecessary merge event.
- Anything more than a simple one-liner patch should be developed in a local branch. In git branches are very lightweight and their use is encouraged. You can create a so-called "feature" branch very easily:
% git branch mychanges % git checkout mychanges % <do your edits and commits> % git checkout master # get back to "trunk" % git pull # update with the central repository. this will be a fastforward % git merge mychanges # merge changes into trunk or % git checkout master % git pull # update master if you want to get updates from central repository % git checkout mychanges # go back to branch % git rebase master # "rebase" the branch patches to HEAD of master % git checkout master % git merge mychanges # will now be a fast forward % git push # send them home
See the discussion in the main Git primer but for short-lived dev branches rebasing would be preferred over merging in that the merging does not really provide useful information for the history of the repository.
You are encouraged to commit often. No patch is too small. For example, you may notice that you have fixed up some documentation whilst doing some other editing in the code, it is possible to commit this documentation patch independently using git add --interactive.
- A linear history is probably easier to deal with than a history with many merges. Git has a facility for making a merge look like a linear history. The git-rebase command is used for this. Rather than try to merge your branch into master in a single commit (note that the full branch history is retained after a merge, but it will be indicated as a true merge when examining the history graphically) an alternative is to "rebase" during the merge. What this means is that git will apply your patches from the branch point to HEAD one at a time as if you had been developing on the trunk all the time. If a conflict occurs then you can fix the conflict and then continue rebasing (note the conflict would have happened during the normal merge process anyhow).
- The only branches that should be stored on the master repository should be release branches created by the release manager. All other development branches should remain local. The local release manager may well tag the point of branch for convenience.
Local tags and public tags are distinct. Think very carefully before pushing a tag to the central repository. ie think before using git push --tags
Resist the temptation to push as soon as you have committed. There is no need to do this unless someone is desperately awaiting your patch. Given the time zone variations there is usually no problem simply deferring pushes until the end of the UK working day (coinciding with the start of the Hawaii work day). This gives you time to determine whether the commit had a problem (for example a file was missing or it included a typo). If you have pushed you can not correct the commit and so a new fix typo commit is required. If you have not pushed you can either reset the commit or amend it (git commit --amend).
- Third party packages are stored in separate git repositories so that they can track vendor releases. They are added to the standard starlink tree as submodules. This requires that edits are done in the separate git checkout and then the submodule is adjusted to track the new update.