workflow.markdown

   1 \r
   2 Overview\r
   3 ========\r
   4 \r
   5 I've found this workflow works well for close-collaboration topic branches in a typical enterprise software development project.\r
   6 \r
   7 By close-collaboration, I mean teams that are frequently collaborating on topic branches via a shared server and so do not to rebase their topic branches all the time.\r
   8 \r
   9 Briefly:\r
  10 \r
  11 * stable replaces master as the "special" branch that is always at the latest released version\r
  12 * topic branches are created off of stable and worked on, merging in results from stable as new releases come out\r
  13 * candidate branches are created as a roll up of several topic branches in anticipation for a release--qa works on the candidate branches and the candidate branch is merged into stable when released\r
  14 \r
  15 stable\r
  16 ======\r
  17 \r
  18 We dropped the master branch and started using "stable" as the branch that represented the latest release. When new a release came out and stable moved, each topic branch would `git merge origin/stable` as needed.\r
  19 \r
  20 To keep the DAG clean, we wanted the first-parent of each commit on stable to be the previous release.\r
  21 \r
  22 This is different than how we first managed stable's DAG, as we'd let stable be fast-forwarded to whatever qa just got done certifying. E.g. it would look like:\r
  23 \r
  24      A                      stable\r
  25      |\\r
  26      | * -- * --            topic1\r
  27      |          \\r
  28      |           * -- B     candidate_1.1        \r
  29      \          /\r
  30        -- * --             topic2\r
  31 \r
  32 And when candidate_1.1 was released, we'd checkout stable, `git merge candidate_1.1` and get a fast-forward so that stable was now at commit B. Which made sense, and worked, but it meant to track the 1.0 -> 1.1 change, you'd have to dig through the topic branch mess between A and B.\r
  33 \r
  34 So we moved to:\r
  35 \r
  36      A --------------- C    stable\r
  37      |\                |\r
  38      | * -- * --       |    topic1\r
  39      |          \      /\r
  40      |           * -- B     candidate_1.1        \r
  41      \          /\r
  42        -- * --             topic2\r
  43 \r
  44 When candidate_1.1 is released, we checkout stable, `git merge --no-ff candidate_1.1` and force a new merge commit. This means commit A (1.0) is a direct first parent of commit C (1.1) and makes the DAG much nicer to follow.\r
  45 \r
  46 Note that the [update-stable][1] hook enforces this first-parent movement of stable and the [update-ensure-follows][2] enforces topic branches merge in the new release at their earliest possible convenience (i.e. before being able to push again).\r
  47 \r
  48 [1]: server/update-stable\r
  49 [2]: server/update-ensure-follows\r
  50 \r
  51 candidates\r
  52 ==========\r
  53 \r
  54 Candidate branches are just gatherings of topic branches that have been deemed releasable by development and qa and so are ready for integration testing.\r
  55 \r
  56 The only trick here is judicious use of `--no-ff` again as otherwise the first topic branch you merge into your new candidate branch will likely result in your candidate branch being fast-forwarded to where ever the topic branch is at.\r
  57 \r
  58 topics\r
  59 ======\r
  60 \r
  61 Topics are fairly obvious.\r
  62 \r
  63 rebase vs. merge\r
  64 ================\r
  65 \r
  66 Merging:\r
  67 \r
  68 * Is great for cross-branch scenarios--merging candidates into stable, stable into topics, etc.\r
  69 * In cross-branch scenarios, fast-forwarding generally isn't preferred as seeing a no-op merge commit into stable or into a new candidate is still useful for DAG aesthetics\r
  70 \r
  71 Rebasing:\r
  72 \r
  73 * Is great for local commits to avoid same-branch merges (where a dev has a local, unshared commit and then creates a useless merge of it into the same branch that has since moved on)\r
  74 * Is a PITA unless you use the [pull][3] scripts\r
  75 \r
  76 [3]: scripts/pull\r
  77 \r