Git, branching conventions and workflow

A description of the conventions we are using to manage the development of dvmdostem and related tool/utilities.

Setup

• Your git remote repositories should be appropriately named. If everyone in our group has repositories that are similarly setup and configured, it is easier to write generic directions and to diagnose problems.

  • origin should point at your fork,
  • upstream should point at ua-snaps github repo.

• Your should definitely go to the effort to display the current git branch in your terminal prompt!.

• git-stash is very handy. Learn to use it!

Workflows

• We are using the "Integration Manager" workflow; generally members of the sel and ua-snap groups on github have push access to github.com/ua-snap/dvm-dos-tem.git

• We are using 2 long-running branches: master and devel. Master is our "production" code. Work done for publication should typically be done with code from the master branch. The devel branch is our "almost production" code. We perform tests before merging into devel and generally try to keep the devel branch stable and readily usable.

Merge vs Pull vs Rebase

There are three concepts can be used to get updates from other developers or the ua-snap repo.

1. Merge - bring modifications from another repository or branck into my another line of work, possibly creating a new commit.

2. Pull - execute a "fetch from a different repository" step before merging.

3. Rebase - "replay" a series of commits onto another part of the history tree.

This article really helped clear up the distinction between merge and rebase and discusses when each is preferable: https://blog.sourcetreeapp.com/2012/08/21/merge-or-rebase/

One problem with a basic merge workflow as opposed to a workflow using rebase is that the default merge messages can a) clutter the history and b) end up confusing if you end up changing a branch name at a later date. For instance if you have a long-running branch with a large feature you are working on and you need to get updates from upstream, if you choose to merge into your "long-running-branch":

$ git checkout long-running-branch
(long-running-branch)$ git pull upstream devel

Then you get a merge message by default that starts with this:

Merge branch 'devel' from github.com:the-upstream/special-project into 'long-running-branch'

All well and good, but later, when I understand the nature of the work on 'long-running-branch' a bit better, I may want to re-name it:

(long-running-branch)$ git checkout -b more-descriptive-name
(more-descriptive-name)$ git branch -D long-running-branch

While renaming the branch is not a problem in and of itself, the merge commit's title will contain "...into 'long-running-branch'". The 'long- running-branch' no longer exists, so the merge commit message will be confusing to anyone who was not involved with 'long-running-branch' or forgot about it. Without good commit messages, it is harder to understand the history and without a good understanding of the history it is easy to lose control of the project.

Links

This page seems to be full of good advice: http://sethrobertson.github.io/GitBestPractices/