Differences between revisions 1 and 2
Deletions are marked like this. Additions are marked like this.
Line 35: Line 35:

[[GitConversion | Details of how the repository was converted to git.]]

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.
  • 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
 % git merge mychanges          # merge changes into trunk
or
 % git rebase mychanges         # or "rebase" them into trunk
 % git push                     # send them home
  • 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. (This needs more clarification).
  • 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.

Details of how the repository was converted to git.

Starlink: GitPolicies (last edited 2009-06-30 08:52:11 by TimJenness)