Page History

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, push your changes and use the Jenkins continuous integration system to request that it be built and tested, along with the rest of the stack. Be sure to log in (using github credentials) before trying to start a run. Then enter your ticket branch name in the Branch entry 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). You can monitor your job on HipChat's "Bot: Jenkins" room. When the Jenkins build passes, ask for your ticket to be reviewed. (Some minor features may not need a review.)
4. To get your ticket reviewed, from the ticket page in JIRA under Workflow click "In Review". In the resulting dialog box assign a reviewer that you think would be appropriate (they have the option to say they cannot review the change, in which case you will have to choose someone else), add a short comment about what it is you want reviewed, an estimate of how long you expect the review to take ("quick" or a "not quick" is sufficient), and add a link to your completed Jenkins build at the end of the comment. You and the reviewer should get an email requesting the review.
   1. It's up to the reviewer to decide whether to create a github pull request or to just let you merge into master as described below. If they do create a pull request, the review comments will be listed there. If they do not, the review comments will go into the JIRA ticket.
5. 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: 

   Code Block
   language bash
   git branch or git status

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

   Code Block
   language bash
   git checkout -b tickets/DM-9999 git push -u origin tickets/DM-9999

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

   Code Block
   language bash
   git commit -a git push

4. Ask for a review. 

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

   Code Block
   language bash theme Confluence
   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. 

...