DEPRECATED

This space is obsolete and unmaintained. The entire content of the DM Developer Guide is now maintained at https://developer.lsst.io .

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

Git References

Git has many similarities to other source code version control systems, but there are important differences as well. There are a number of useful references to help you master your use of git: 

  • git Reference -- read this first to get a high-level overview in 15 minutes

  • Learn.git series -- another git introduction, including screen-casts (note: the text may be somewhat more informative than the embedded screencasts)

  • http://git-scm.com/course/svn.html -- git for svn users (but please, read the links above as well)

  • Pro Git book -- Written by Scott Chacon. Get to know git in more depth (~2 hrs?)

  • Git Book -- similar to the Pro Git book, but a bit more comprehensive

  • Useful git tips -- some useful less well known tips

  • An explanation from Mario Juric of how to think about git and how it internally does things. It also discusses merging and fast-forwards. Note that most of this is covered in the tutorials above, but if you're still confused, try reading it.
  • A video by Phil Marshall on using git and GitHub.

A cookbook style document, Git Crash Course, may help you understand the use of git for LSST/DM code development. 

Development Policies

Branch Management Policies

LSST DM code development is governed by various policies to maintain order in a large, distributed, multi-developer project. The policies are embodied in the workflows described below. Note: the branch management policy described here is drawn from the page: DM Branching Policy which is the authoritative source. 

Git Workflow

The following workflow is based on github-flow: 

  1. Anything in the master branch is deployable (i.e., should always run and generate correct output). Developing directly on the master branch is forbidden.  (But, as a special exception, documentation authoring and fixing may occur directly on master.)
  2. Feature (and bugfix) development must always happen in branches. It is advisable to commit early and often to your branch. You should never merge master into your feature branch; if you need to include changes on master in a feature branch, you should use rebase to rewrite the history of the feature branch such that all feature branch commits happen after all master commits (on the feature branch, just do "git rebase master"). This prevents complex commit histories.
  3. When your feature is ready, use the Jenkins continuous integration system to request that it be built and tested along with the rest of the stack.  Put your ticket branch name in the form and leave the rest as defaulted (i.e. you want to build the entire stack using your ticket and run the demo as a minimal integration test).  When that passes, ask for it to be reviewed. (Some minor features may not need a review.)
  4. A feature that passes code review is permitted to be merged into master. Merge it (be sure to use the "--no-ff" option, as described below).  Jenkins and buildbot will notice and will build and test it (again).

If a release date is approaching, a release integration branch may be created; only mandatory release fixes should go on such a branch (and usually be cherry-picked to master as well).  Normal development on master will continue.

For maintenance on "stable" releases, a separate release maintenance branch may be created if necessary.  Only bug fixes should go on such a branch (and again usually be cherry-picked to master). 

An example workflow for developing a new feature is the following: 

  1. Verify which branch you are on. Ordinarily that would be the git master branch: 

    git branch
or
git status

  2. Create a new branch for ticket DM-9999, both locally and remotely: 

    git checkout -b tickets/DM-9999
git push -u origin tickets/DM-9999

  3. Create or modify the source code. Commit often: Push periodically: 

    git commit -a
git push
  4. Ask for a review. 

  5. After your code passes review, merge it into master: 

    git checkout master
git pull master
git merge --no-ff tickets/DM-9999
git push

Git Tag Policy

When creating tags meant for the public (e.g., release tags), always use annotated tags (that is, 'git tag -a') or signed tags ('git tag -s'). These store the information on who created the tag, when, can be cryptographically signed, and can have a message attached to them. For example: 

git tag -a -m "Version 4.7.0.0" 4.7.0.0

or, with signing: 

git tag -s -m "Version 4.7.0.0" 4.7.0.0

Summary of Git Operations

The following illustrates the sequence of operations one ordinarily executes with git during source code development. 

 

  • No labels