Documentation/howto/maintain-git.txt

   1 From: Junio C Hamano <gitster@pobox.com>
   2 Date: Wed, 21 Nov 2007 16:32:55 -0800
   3 Subject: Addendum to "MaintNotes"
   4 Abstract: Imagine that git development is racing along as usual, when our friendly
   5  neighborhood maintainer is struck down by a wayward bus. Out of the
   6  hordes of suckers (loyal developers), you have been tricked (chosen) to
   7  step up as the new maintainer. This howto will show you "how to" do it.
   8
   9 The maintainer's git time is spent on three activities.
  10
  11  - Communication (60%)
  12
  13    Mailing list discussions on general design, fielding user
  14    questions, diagnosing bug reports; reviewing, commenting on,
  15    suggesting alternatives to, and rejecting patches.
  16
  17  - Integration (30%)
  18
  19    Applying new patches from the contributors while spotting and
  20    correcting minor mistakes, shuffling the integration and
  21    testing branches, pushing the results out, cutting the
  22    releases, and making announcements.
  23
  24  - Own development (10%)
  25
  26    Scratching my own itch and sending proposed patch series out.
  27
  28 The policy on Integration is informally mentioned in "A Note
  29 from the maintainer" message, which is periodically posted to
  30 this mailing list after each feature release is made.
  31
  32 The policy.
  33
  34  - Feature releases are numbered as vX.Y.Z and are meant to
  35    contain bugfixes and enhancements in any area, including
  36    functionality, performance and usability, without regression.
  37
  38  - Maintenance releases are numbered as vX.Y.Z.W and are meant
  39    to contain only bugfixes for the corresponding vX.Y.Z feature
  40    release and earlier maintenance releases vX.Y.Z.V (V < W).
  41
  42  - 'master' branch is used to prepare for the next feature
  43    release. In other words, at some point, the tip of 'master'
  44    branch is tagged with vX.Y.Z.
  45
  46  - 'maint' branch is used to prepare for the next maintenance
  47    release.  After the feature release vX.Y.Z is made, the tip
  48    of 'maint' branch is set to that release, and bugfixes will
  49    accumulate on the branch, and at some point, the tip of the
  50    branch is tagged with vX.Y.Z.1, vX.Y.Z.2, and so on.
  51
  52  - 'next' branch is used to publish changes (both enhancements
  53    and fixes) that (1) have worthwhile goal, (2) are in a fairly
  54    good shape suitable for everyday use, (3) but have not yet
  55    demonstrated to be regression free.  New changes are tested
  56    in 'next' before merged to 'master'.
  57
  58  - 'pu' branch is used to publish other proposed changes that do
  59    not yet pass the criteria set for 'next'.
  60
  61  - The tips of 'master', 'maint' and 'next' branches will always
  62    fast-forward, to allow people to build their own
  63    customization on top of them.
  64
  65  - Usually 'master' contains all of 'maint', 'next' contains all
  66    of 'master' and 'pu' contains all of 'next'.
  67
  68  - The tip of 'master' is meant to be more stable than any
  69    tagged releases, and the users are encouraged to follow it.
  70
  71  - The 'next' branch is where new action takes place, and the
  72    users are encouraged to test it so that regressions and bugs
  73    are found before new topics are merged to 'master'.
  74
  75
  76 A typical git day for the maintainer implements the above policy
  77 by doing the following:
  78
  79  - Scan mailing list and #git channel log.  Respond with review
  80    comments, suggestions etc.  Kibitz.  Collect potentially
  81    usable patches from the mailing list.  Patches about a single
  82    topic go to one mailbox (I read my mail in Gnus, and type
  83    \C-o to save/append messages in files in mbox format).
  84
  85  - Review the patches in the saved mailboxes.  Edit proposed log
  86    message for typofixes and clarifications, and add Acks
  87    collected from the list.  Edit patch to incorporate "Oops,
  88    that should have been like this" fixes from the discussion.
  89
  90  - Classify the collected patches and handle 'master' and
  91    'maint' updates:
  92
  93    - Obviously correct fixes that pertain to the tip of 'maint'
  94      are directly applied to 'maint'.
  95
  96    - Obviously correct fixes that pertain to the tip of 'master'
  97      are directly applied to 'master'.
  98
  99    This step is done with "git am".
 100
 101      $ git checkout master    ;# or "git checkout maint"
 102      $ git am -3 -s mailbox
 103      $ make test
 104
 105  - Merge downwards (maint->master):
 106
 107      $ git checkout master
 108      $ git merge maint
 109      $ make test
 110
 111  - Review the last issue of "What's cooking" message, review the
 112    topics scheduled for merging upwards (topic->master and
 113    topic->maint), and merge.
 114
 115      $ git checkout master    ;# or "git checkout maint"
 116      $ git merge ai/topic     ;# or "git merge ai/maint-topic"
 117      $ git log -p ORIG_HEAD.. ;# final review
 118      $ git diff ORIG_HEAD..   ;# final review
 119      $ make test              ;# final review
 120      $ git branch -d ai/topic ;# or "git branch -d ai/maint-topic"
 121
 122  - Merge downwards (maint->master) if needed:
 123
 124      $ git checkout master
 125      $ git merge maint
 126      $ make test
 127
 128  - Merge downwards (master->next) if needed:
 129
 130      $ git checkout next
 131      $ git merge master
 132      $ make test
 133
 134  - Handle the remaining patches:
 135
 136    - Anything unobvious that is applicable to 'master' (in other
 137      words, does not depend on anything that is still in 'next'
 138      and not in 'master') is applied to a new topic branch that
 139      is forked from the tip of 'master'.  This includes both
 140      enhancements and unobvious fixes to 'master'.  A topic
 141      branch is named as ai/topic where "ai" is typically
 142      author's initial and "topic" is a descriptive name of the
 143      topic (in other words, "what's the series is about").
 144
 145    - An unobvious fix meant for 'maint' is applied to a new
 146      topic branch that is forked from the tip of 'maint'.  The
 147      topic is named as ai/maint-topic.
 148
 149    - Changes that pertain to an existing topic are applied to
 150      the branch, but:
 151
 152      - obviously correct ones are applied first;
 153
 154      - questionable ones are discarded or applied to near the tip;
 155
 156    - Replacement patches to an existing topic are accepted only
 157      for commits not in 'next'.
 158
 159    The above except the "replacement" are all done with:
 160
 161      $ git am -3 -s mailbox
 162
 163    while patch replacement is often done by:
 164
 165      $ git format-patch ai/topic~$n..ai/topic ;# export existing
 166
 167    then replace some parts with the new patch, and reapplying:
 168
 169      $ git reset --hard ai/topic~$n
 170      $ git am -3 -s 000*.txt
 171
 172    The full test suite is always run for 'maint' and 'master'
 173    after patch application; for topic branches the tests are run
 174    as time permits.
 175
 176  - Update "What's cooking" message to review the updates to
 177    existing topics, newly added topics and graduated topics.
 178
 179    This step is helped with Meta/cook script (where Meta/ contains
 180    a checkout of the 'todo' branch).
 181
 182  - Merge topics to 'next'.  For each branch whose tip is not
 183    merged to 'next', one of three things can happen:
 184
 185    - The commits are all next-worthy; merge the topic to next:
 186
 187      $ git checkout next
 188      $ git merge ai/topic     ;# or "git merge ai/maint-topic"
 189      $ make test
 190
 191    - The new parts are of mixed quality, but earlier ones are
 192      next-worthy; merge the early parts to next:
 193
 194      $ git checkout next
 195      $ git merge ai/topic~2   ;# the tip two are dubious
 196      $ make test
 197
 198    - Nothing is next-worthy; do not do anything.
 199
 200  - [** OBSOLETE **] Optionally rebase topics that do not have any commit
 201    in next yet, when they can take advantage of low-level framework
 202    change that is merged to 'master' already.
 203
 204      $ git rebase master ai/topic
 205
 206    This step is helped with Meta/git-topic.perl script to
 207    identify which topic is rebaseable.  There also is a
 208    pre-rebase hook to make sure that topics that are already in
 209    'next' are not rebased beyond the merged commit.
 210
 211  - [** OBSOLETE **] Rebuild "pu" to merge the tips of topics not in 'next'.
 212
 213      $ git checkout pu
 214      $ git reset --hard next
 215      $ git merge ai/topic     ;# repeat for all remaining topics
 216      $ make test
 217
 218    This step is helped with Meta/PU script
 219
 220  - Push four integration branches to a private repository at
 221    k.org and run "make test" on all of them.
 222
 223  - Push four integration branches to /pub/scm/git/git.git at
 224    k.org.  This triggers its post-update hook which:
 225
 226     (1) runs "git pull" in $HOME/git-doc/ repository to pull
 227         'master' just pushed out;
 228
 229     (2) runs "make doc" in $HOME/git-doc/, install the generated
 230         documentation in staging areas, which are separate
 231         repositories that have html and man branches checked
 232         out.
 233
 234     (3) runs "git commit" in the staging areas, and run "git
 235         push" back to /pub/scm/git/git.git/ to update the html
 236         and man branches.
 237
 238     (4) installs generated documentation to /pub/software/scm/git/docs/
 239         to be viewed from http://www.kernel.org/
 240
 241  - Fetch html and man branches back from k.org, and push four
 242    integration branches and the two documentation branches to
 243    repo.or.cz and other mirrors.
 244
 245
 246 Some observations to be made.
 247
 248  * Each topic is tested individually, and also together with
 249    other topics cooking in 'next'.  Until it matures, none part
 250    of it is merged to 'master'.
 251
 252  * A topic already in 'next' can get fixes while still in
 253    'next'.  Such a topic will have many merges to 'next' (in
 254    other words, "git log --first-parent next" will show many
 255    "Merge ai/topic to next" for the same topic.
 256
 257  * An unobvious fix for 'maint' is cooked in 'next' and then
 258    merged to 'master' to make extra sure it is Ok and then
 259    merged to 'maint'.
 260
 261  * Even when 'next' becomes empty (in other words, all topics
 262    prove stable and are merged to 'master' and "git diff master
 263    next" shows empty), it has tons of merge commits that will
 264    never be in 'master'.
 265
 266  * In principle, "git log --first-parent master..next" should
 267    show nothing but merges (in practice, there are fixup commits
 268    and reverts that are not merges).
 269
 270  * Commits near the tip of a topic branch that are not in 'next'
 271    are fair game to be discarded, replaced or rewritten.
 272    Commits already merged to 'next' will not be.
 273
 274  * Being in the 'next' branch is not a guarantee for a topic to
 275    be included in the next feature release.  Being in the
 276    'master' branch typically is.