Differences between revisions 3 and 4
Deletions are marked like this. Additions are marked like this.
Line 13: Line 13:
 * Use ''git pull --rebase'' if you are developing in master and updating from the remote. This prevents an unnecessary merge event.
Line 19: Line 21:
 % git pull # update with the central repository  % git pull # update with the central repository. this will be a fastforward
Line 25: Line 27:

See the discussion in the main [[GitPrimer | 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.
Line 34: Line 38:
 * 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'').

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 rebase mychanges         # or "rebase" them into trunk
 % 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.

Details of how the repository was converted to git.

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