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
- branch from develop
- code
- review
- merge back into develop
Create a release
- branch from develop
- bug fix
- QA
- 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/'
- 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-bugrelease 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.2with 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 developwith git-flow:
git flow feature start <feature>Pushing/fetching feature branch to server (optional)
straight git:
git push origin myfeaturewith 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 developwith git-flow:
git flow feature finish <feature>Deleting remote branches after merge
straight git:
git push origin :myfeaturewith git-flow:
funktion not implementedhotfix 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