git checkout -b ISIS-999
These notes recommend how contributors should work with git. To understand these notes, the only real concepts that you need to grok are:
git commits form an acyclic graph, with each commit pointing to its parent commit (or commits, if a merge)
a branch is merely a pointer to one of these commits; git calls the main branch master
git commits happen in two steps: first they are added to the index (also called the staging area), then they are committed.
For more background reading, see:
Pro Git book (free in electronic form)
git reset demystified - differentiating the working directory vs index/staging area
And, of course, there is loads of good advice on stackoverflow.com
There are many ways of using Git, but the Isis committers have adopted the following workflow:
create a topic branch for a feature
git checkout -b ISIS-999
periodically, push the branch to origin (for safekeeping):
git push origin ISIS-999
rebase
the topic branch periodically on master.
How often you do this will depend on whether you are collaborating with others on the feature. You need to ensure that your co-worker has no outstanding work before you do this; otherwise it’ll create merge conflict hell for them:
git checkout master
git pull
git checkout ISIS-999
git rebase master
git push origin ISIS-999 --force
when feature is complete, rebase once more (as above), then switch to master and perform a merge --no-ff
:
git checkout master
git merge --no-ff ISIS-999
finally, remove the branch
git branch -d ISIS-999
git push origin --delete ISIS-999
This way of working gives us the full history on the branch as to what the thought processes were for the feature, but only a single commit on to master
to see the ultimate impact of the changes (acting a bit like a summary).
The minimum we expect in a commit messages is:
ISIS-nnn: brief summary here
- optionally, longer details
- should be written here
- in bullet points
where ISIS-nnn
is a ticket raised in our JIRA issue tracker.
For non-committers we typically expect more detail again; see the contributing page for the longer format recommended for contributors to use.