Changes between Version 1 and Version 2 of doc/OONI/DevelopmentWorkflow


Ignore:
Timestamp:
Apr 19, 2013, 2:00:48 PM (6 years ago)
Author:
isis
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • doc/OONI/DevelopmentWorkflow

    v1 v2  
    22--------------------------------------
    33This 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
     4
     5== Overview / tl;dr ==
     6In addition to each ooni developer's personal repositories, there are two common repositories. The [https://gitweb.torproject.org/ooniprobe.git official one is here] on torproject.org. The other is [https://github.com/TheTorProject/ooni-probe 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.
     7
     8The main branching workflow looks like this:
     9{{{
     10               __________                                 ________
     11              |==|=======|                               |==|=====|
     12              |  | tor   |                               |  | git |
     13              |  |project|                               |  | hub |
     14              |  | .org  |                               |  | repo|
     15              |  |   repo|                               |  |     |
     16              |  |======?|   These should be synced:     |  |====?|
     17              |__|_______|   '-----------------------'   |__|_____|
     18                     |      ____________________________      ^
     19                     |      \              \            \     |
     20             .-------------->) tpo-common   ) gh-common  )----'
     21             |              /______________/____________/
     22             |                    |
     23             |                    |
     24             |                    v
     25             |         ___________________________________________________________
     26  .--------------------\                   \                  \                   \
     27 ( tpo-common/release-* ) tpo-common/master ) gh-common/master ) gh-common/develop )<----------------------------------------------------.
     28  '--------------------/___________________/__________________/___________________/                                                      |
     29 ^           |                    |                                                                                                      |
     30 |           v                    |                                                                                                      |
     31 |  .-----------------.           |                                               .-------------------------------------------.          |
     32 '-( tpo-common/hotfix )          |            Developers work in named branches:( <name>/<branch_type>/<ticket>-<description> )         |
     33    '-----------------'           |                                               '-------------------------------------------'          |
     34                                  |        _______________________________________                                                       |
     35                      (\_/)       |        \                  \                   \  .----------------------------------.                |
     36                      (O.o)-------'-------->) isis/master      ) isis/develop      )( isis/testing/hellais/awesome-thing )<--------------.
     37                      (> <)       |        /__________________/___________________/  '----------------------------------'                |
     38                      isis        |                                      |                                                               |
     39                 (ooni developer) |                                      |   .---------------------------------.                         |
     40                                  |                                      '->( isis/feature/####-supercool-thing )                        |
     41                                  |                                      |   '---------------------------------'                 .--------------.
     42                                  |                                      |   .-------------------------------.                   |              |
     43                                  |                                      '->( isis/fix/####-some-twisted-crap )----------------->| pull request |
     44                                  |                                          '-------------------------------'                   |              |
     45                                  |                                                                                              '--------------'
     46                                  |        _______________________________________                                                 |     ^
     47                     (\_/)        |        \                   \                  \  .--------------------------------------.      |     |
     48                     (O.o)--------'-------->) hellais/master    ) hellais/develop  )( hellais/testing/isis/some-twisted-crap )<----'     |
     49                     (> <)                 /___________________/__________________/  '--------------------------------------'            |
     50                     hellais                                             |                                                               |
     51                 (ooni developer)                                        |                                                               |
     52        (\_/)                                                            |   .----------------------------------.                        |
     53        (O.o)                                                            |->( hellais/feature/####-awesome-thing )-----------------------'
     54        (> <)                                                            |   '----------------------------------'
     55     **********    (\_/)                                                 |   .--------------------------------------.
     56     * aagbsn *    (O.o)                                                 |->( hellais/fix/####-some-thing-that-broke )
     57     **********    (> <)                                                 |   '--------------------------------------'
     58                 ***********     ** I don't want to draw                 |   .------------------------------.
     59                 * ioerror *        all of the things.                   '->( hellais/fix/####-supercatsulla )
     60                 ***********                                                 '------------------------------'
     61}}}
    462
    563'''Create a new feature'''
     
    2179HEAD always represents a production ready state.
    2280
    23 * immortal: this branch lives forever
    24 * merge from: release
    25 * branch to: hotfix
     81 * immortal: this branch lives forever
     82 * merge from: release
     83 * branch to: hotfix
    2684
    2785=== develop branch ===
    2886HEAD always represents staging for next release.
    2987
    30 * immortal: this branch lives forever
    31 * commits: minor changes. big changes should be committed in feature branches.
    32 * merge from: release branches, feature branches.
    33 * branch to: feature branches
     88 * immortal: this branch lives forever
     89 * commits: minor changes. big changes should be committed in feature branches.
     90 * merge from: release branches, feature branches.
     91 * branch to: feature branches
     92
     93=== testing branch ===
     94HEAD represents the tip of the branch currently being tested, rebased onto the develop branch.
     95
     96The purpose of this branch is to push a temporary testing stage to [https://travis-ci.org/TheTorProject/ooni-probe Travis-CI].
     97
     98 * named 'testing/<name of branch being rebased onto develop for testing>'
     99 * mortal: only exists while waiting for the build results from the continuous integration system
     100 * branch from: develop branch
     101 * merge from: feature branches, fix branches
     102 * commits: none
     103
     104For 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:
     105{{{
     106## update the commonly-shared staging area:
     107git fetch tpo-common
     108git checkout develop
     109git merge --ff-only tpo-common/develop
     110
     111## retrieve the branch to test:
     112git fetch hellais
     113git checkout hellais/fix/1234-fix-some-bug
     114git checkout -b testing/hellais/fix/1234-fix-some-bug
     115git rebase develop
     116git push isislovecruft testing/hellais/fix/1234-fix-some-bug
     117}}}
    34118
    35119=== release branches ===
    36 one branch per release, only bugfix commits, once tagged with release version number, it gets merged back into both master and develop and is then killed off.
    37 
    38 * name starts with 'release-'
    39 * mortal: live for a limited time
    40 * commits: bugfixes only
    41 * branch from: develop
    42 * merge from: none
    43 * merge to: master and develop (at same time, once tagged)
     120One 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.
     121
     122 * name starts with 'release-'
     123 * mortal: live for a limited time
     124 * commits: bugfixes only
     125 * branch from: develop
     126 * merge from: none
     127 * merge to: master and develop (at same time, once tagged)
    44128
    45129Creating a new release branch
     
    77161Most development happens here. Merges from and to develop branch only.
    78162
    79 * mortal: live for a limited time
    80 * commits: the sky is the limit
    81 * branch from: develop
    82 * merge to: develop
     163 * mortal: live for a limited time
     164 * commits: the sky is the limit
     165 * branch from: develop
     166 * merge to: develop
    83167
    84168'''Creating feature branch'''
     
    137221A temporary development branch for quick and urgent changes to the current master branch. It is like a release branch combined with a develop branch.
    138222
    139 * name starts with 'hotfix-'
    140 * branch from: master
    141 * merge to: develop, master
     223 * name starts with 'hotfix-'
     224 * branch from: master
     225 * merge to: develop, master
    142226
    143227Creating a hotfix branch