Git/Workflow/Topic

Introduction

We define two branch types:

• Topic Branch
  • Commits represent changes (real work)
  • Distinguished by feature (one topic per feature or fix)
  • Named locally by each developer (describe purpose of work)
  • Heads not published (no named branch on server)
• Integration Branch
  • Commits represent merges (merge topics together)
  • Distinguished by stability (release maintenance, release preparation, development edge)
  • Named everywhere
  • Heads published on server

See also git help workflows.

Integration Branches

We use an integration branch for each stage of development:

• maint: Release maintenance (high stability). Only bug fixes should be published here. Only the release manager can push here.
• master: Release preparation (medium stability). Only mature features and bug fixes should be published here.
• next: Development (low stability). New features should be published here.

Notation

This document uses ascii-art to depict commit history:

Branch name	master
Current branch	*master
Commit with parent in same branch	----o
Commit with parent in another branch	\ o
Commit with two parents (merge)	----o /
Commit with arbitrary ancestry	...o

Development

We cover below the steps to take during each phase of development.

New Topic

Create a new topic branch for each separate feature or bug fix. Always start the topic from a stable integration branch, usually master. If the topic fixes a bug in the current release, use maint. Never start a topic from next! In the following table we review the steps and commands to create, develop, and publish a topic branch based on master.

Actions	Results
Update master to base work on the most recently integrated features.
$ git checkout master	...o *master
$ git pull	...o----o *master
Create the local topic branch. Use a meaningful name for "topic". Name topics like you might name functions: concise but precise. A reader should have a general idea of the change to be made given just the branch name.
$ git checkout -b topic	...o----o master ^ *topic
This is where the real work happens. Edit, stage, and commit files repeatedly as needed for your work. During this step, avoid the "urge to merge" from an integration branch. Your changes are safely committed; you can merge your work with others when you are finished.
$ edit files $ git add -- files $ git commit	...o----o master \ o *topic
$ edit files $ git add -- files $ git commit	...o----o master \ o----o *topic
When the topic is ready for publication it must be merged into next. Do not merge from next! It should be the current local branch when you merge. Switch to next and update it. Use "git checkout -b next origin/next" to create a local next the first time.
$ git checkout next $ git pull	...o----o master . \ . o----o topic . ........o *next
Merge the topic and test it.
$ git merge topic	...o----o master . \ . o----o topic . \ ........o----o *next
Finally, publish the change.
$ git push

Mature Topic

When a topic is ready for inclusion in the next release, we merge it into master.

Actions	Results
Update master to get the latest work by others. We will merge the topic into it.
$ git checkout master	...o----o *master . \ . o----o topic . \ ........o----o next
$ git pull	.......... . \ ...o----o----o *master . \ . o----o topic . \ ........o----o next
Merge the topic and test it.
$ git merge topic	.......... . \ ...o----o----o---o *master . \ / . o----o topic . \ ........o----o next
Delete the local branch.
$ git branch -d topic	.......... . \ ...o----o----o---o *master . \ / . o----o . \ ........o----o next
Finally, publish the change.
$ git push

Old Topic

Sometimes we need to continue work on an old topic that has already been merged to an integration branch and for which we no longer have a local topic branch. To revive an old topic, we create a local branch based on the last commit from the topic (this is not one of the merges into an integration branch).

First we need to identify the commit by its hash. It is an ancestor of the integration branch into which it was once merged, say next. Run git log with the --first-parent option to view the integration history:

$ git log --first-parent next
commit 9057863...
Merge: 2948732 a348901
...
    Merge branch topicA

commit 2948732...
Merge: 1094687 b235725
...
    Merge branch topicB

commit 1094687...
Merge: 8267263 c715789
...
    Merge branch topicC

Locate the merge commit for the topic of interest, say topicB. It's second parent is the commit from which we will restart work (b235725 in this example).

Actions	Results
Create a local topic branch starting from the commit identified above.
$ git checkout -b topic b235725	.......... . \ ...o----o----o---o master . \ / . o----o *topic (b235725) . \ ........o----o----o next / / c715789 a348901