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 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:
- 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.)
- Feature (and bugfix) development must always happen in branches. It is advisable to commit early and often to your branch. However, you should not merge the master into your feature branch unless you absolutely need some new feature that has been developed in the master in the meantime. This prevents complex commit histories.
- When your feature is ready, use the buildbot continuous integration system to request that it be built and tested along with the rest of the stack. When that passes, ask for it to be reviewed. (Some minor features may not need a review.)
- A feature that passes code review is permitted to be merged into master. Merge it. buildbot will notice and will build and test it (again).
If a release date is approaching and some work is occurring that is not part of the release, a next branch may be created for non-release integration. The same workflow should be applied to next. After the release, next will typically be rebased on top of (the previous) master and renamed to be the new master.
For maintenance on "stable" releases, create a separate release branch (e.g., "R4.0"), and apply exactly the same flow to that branch (except that only bugfixes would be allowed).
An example workflow for developing a new feature is the following:
Verify which branch you are on. Ordinarily that would be the git master branch:
git branch or git status
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
Create or modify the source code. Commit often: Push periodically:
git commit -a git push
- Ask for a review.
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.