wiki:doc/OONI/DevelopmentWorkflow

Development Workflow


This is a proposed formalisation of our accepted common development workflow. This text is taken from one of the wiki pages of another project I work on, and I thought it was really convenient for preventing people from getting really confused about each other's git branches. We should discuss this, add any changes after discussing them, and finalise this. <(A)3 isis

Overview / tl;dr

In addition to each ooni developer's personal repositories, there are two common repositories. The official one is here on torproject.org. The other is on github, and is used mainly for our code review process between developers, although it also exists as a friendlier interface for pull requests from potential contributors.

The main branching workflow looks like this:

               __________                                 ________
              |==|=======|                               |==|=====|
              |  | tor   |                               |  | git |
              |  |project|                               |  | hub |
              |  | .org  |                               |  | repo|
              |  |   repo|                               |  |     |
              |  |======?|   These should be synced:     |  |====?|
              |__|_______|   '-----------------------'   |__|_____|
                     |      ____________________________      ^
                     |      \              \            \     |
             .-------------->) tpo-common   ) gh-common  )----'
             |              /______________/____________/
             |                    |
             |                    |
             |                    v
             |         ___________________________________________________________
  .--------------------\                   \                  \                   \
 ( tpo-common/release-* ) tpo-common/master ) gh-common/master ) gh-common/develop )<----------------------------------------------------.
  '--------------------/___________________/__________________/___________________/                                                      |
 ^           |                    |                                                                                                      |
 |           v                    |                                                                                                      |
 |  .-----------------.           |                                               .-------------------------------------------.          |
 '-( tpo-common/hotfix )          |            Developers work in named branches:( <name>/<branch_type>/<ticket>-<description> )         |
    '-----------------'           |                                               '-------------------------------------------'          |
                                  |        _______________________________________                                                       |
                      (\_/)       |        \                  \                   \  .----------------------------------.                |
                      (O.o)-------'-------->) isis/master      ) isis/develop      )( isis/testing/hellais/awesome-thing )<--------------.
                      (> <)       |        /__________________/___________________/  '----------------------------------'                |
                      isis        |                                      |                                                               |
                 (ooni developer) |                                      |   .---------------------------------.                         |
                                  |                                      '->( isis/feature/####-supercool-thing )                        |
                                  |                                      |   '---------------------------------'                 .--------------.
                                  |                                      |   .-------------------------------.                   |              |
                                  |                                      '->( isis/fix/####-some-twisted-crap )----------------->| pull request |
                                  |                                          '-------------------------------'                   |              |
                                  |                                                                                              '--------------'
                                  |        _______________________________________                                                 |     ^
                     (\_/)        |        \                   \                  \  .--------------------------------------.      |     |
                     (O.o)--------'-------->) hellais/master    ) hellais/develop  )( hellais/testing/isis/some-twisted-crap )<----'     |
                     (> <)                 /___________________/__________________/  '--------------------------------------'            |
                     hellais                                             |                                                               |
                 (ooni developer)                                        |                                                               |
        (\_/)                                                            |   .----------------------------------.                        |
        (O.o)                                                            |->( hellais/feature/####-awesome-thing )-----------------------'
        (> <)                                                            |   '----------------------------------'
     **********    (\_/)                                                 |   .--------------------------------------.
     * aagbsn *    (O.o)                                                 |->( hellais/fix/####-some-thing-that-broke )
     **********    (> <)                                                 |   '--------------------------------------'
                 ***********     ** I don't want to draw                 |   .------------------------------.
                 * ioerror *        all of the things.                   '->( hellais/fix/####-supercatsulla )
                 ***********                                                 '------------------------------'

Create a new feature

  1. branch from develop
  2. code
  3. review
  4. merge back into develop

Create a release

  1. branch from develop
  2. bug fix
  3. QA
  4. tag, and merge back into develop and master

Branches

See A successful git branching model for more information. The slight modification we make is that release tags are made in the release branch before getting merged to master, rather than getting tagged in master.

master branch

HEAD always represents a production ready state.

  • immortal: this branch lives forever
  • merge from: release
  • branch to: hotfix

develop branch

HEAD always represents staging for next release.

  • immortal: this branch lives forever
  • commits: minor changes. big changes should be committed in feature branches.
  • merge from: release branches, feature branches.
  • branch to: feature branches

testing branch

HEAD represents the tip of the branch currently being tested, rebased onto the develop branch.

The purpose of this branch is to push a temporary testing stage to Travis-CI.

  • named 'testing/<name of branch being rebased onto develop for testing>'
  • mortal: only exists while waiting for the build results from the continuous integration system
  • branch from: develop branch
  • merge from: feature branches, fix branches
  • commits: none

For example, if isis is reviewing hellais' code in hellais' branch 'fix/1234-fix-some-bug' and wants to check that merging the pull request into the current common staging area (the 'develop' branch) will not result in any unforeseen errors:

## update the commonly-shared staging area:
git fetch tpo-common
git checkout develop
git merge --ff-only tpo-common/develop

## retrieve the branch to test:
git fetch hellais
git checkout hellais/fix/1234-fix-some-bug
git checkout -b testing/hellais/fix/1234-fix-some-bug
git rebase develop
git push isislovecruft testing/hellais/fix/1234-fix-some-bug

release branches

One branch per release; only bugfix commits may be made directly on these branches. Once it is tagged (tag must be signed) with release version number, it gets merged back into both master and develop and is then killed off.

  • name starts with 'release-'
  • mortal: live for a limited time
  • commits: bugfixes only
  • branch from: develop
  • merge from: none
  • merge to: master and develop (at same time, once tagged)

Creating a new release branch

straight git:

git checkout -b release-1.2 develop
./bump-version.sh 1.2
git commit -a -m "Bumped version number to 1.2"

with git-flow:

git flow release start <release>

Finalizing a release

straight git:

git checkout release-1.2
git tag -a 1.2 -s
git checkout master
git merge --no-ff release-1.2
git checkout develop
git merge --no-ff release-1.2
git branch -d release-1.2

with git-flow:

git flow release finish <release>

feature branches

Most development happens here. Merges from and to develop branch only.

  • mortal: live for a limited time
  • commits: the sky is the limit
  • branch from: develop
  • merge to: develop

Creating feature branch

straight git:

git checkout -b myfeature develop

with git-flow:

git flow feature start <feature>

Pushing/fetching feature branch to server (optional)

straight git:

git push origin myfeature

with git-flow:

git flow feature publish <feature>
git flow feature pull <remote> <feature>

Merging feature back into develop

straight git:

git checkout develop
git merge --no-ff myfeature
git branch -d myfeature
git push origin develop

with git-flow:

git flow feature finish <feature>

Deleting remote branches after merge

straight git:

git push origin :myfeature

with git-flow:

funktion not implemented

hotfix branches

A temporary development branch for quick and urgent changes to the current master branch. It is like a release branch combined with a develop branch.

  • name starts with 'hotfix-'
  • branch from: master
  • merge to: develop, master

Creating a hotfix branch

git checkout -b hotfix-1.2.1 master
./bump-version.sh 1.2.1
git commit -a -m "Bumped version number to 1.2.1"

Finalizing a hotfix

git checkout hotfix-1.2.1
git tag -a 1.2.1 -s
git checkout master
git merge --no-ff hotfix-1.2.1
git checkout develop
git merge --no-ff hotfix-1.2.1
git branch -d hotfix-1.2.1
Last modified 5 years ago Last modified on Apr 19, 2013, 2:00:48 PM