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/UWC 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  - Rebase topics that do not have any commit in next yet.  This
 201    step is optional but sometimes is worth doing when an old
 202    series that is not in next can take advantage of low-level
 203    framework change that is merged to 'master' already.
 204
 205      $ git rebase master ai/topic
 206
 207    This step is helped with Meta/git-topic.perl script to
 208    identify which topic is rebaseable.  There also is a
 209    pre-rebase hook to make sure that topics that are already in
 210    'next' are not rebased beyond the merged commit.
 211
 212  - Rebuild "pu" to merge the tips of topics not in 'next'.
 213
 214      $ git checkout pu
 215      $ git reset --hard next
 216      $ git merge ai/topic     ;# repeat for all remaining topics
 217      $ make test
 218
 219    This step is helped with Meta/PU script
 220
 221  - Push four integration branches to a private repository at
 222    k.org and run "make test" on all of them.
 223
 224  - Push four integration branches to /pub/scm/git/git.git at
 225    k.org.  This triggers its post-update hook which:
 226
 227     (1) runs "git pull" in $HOME/git-doc/ repository to pull
 228         'master' just pushed out;
 229
 230     (2) runs "make doc" in $HOME/git-doc/, install the generated
 231         documentation in staging areas, which are separate
 232         repositories that have html and man branches checked
 233         out.
 234
 235     (3) runs "git commit" in the staging areas, and run "git
 236         push" back to /pub/scm/git/git.git/ to update the html
 237         and man branches.
 238
 239     (4) installs generated documentation to /pub/software/scm/git/docs/
 240         to be viewed from http://www.kernel.org/
 241
 242  - Fetch html and man branches back from k.org, and push four
 243    integration branches and the two documentation branches to
 244    repo.or.cz
 245
 246
 247 Some observations to be made.
 248
 249  * Each topic is tested individually, and also together with
 250    other topics cooking in 'next'.  Until it matures, none part
 251    of it is merged to 'master'.
 252
 253  * A topic already in 'next' can get fixes while still in
 254    'next'.  Such a topic will have many merges to 'next' (in
 255    other words, "git log --first-parent next" will show many
 256    "Merge ai/topic to next" for the same topic.
 257
 258  * An unobvious fix for 'maint' is cooked in 'next' and then
 259    merged to 'master' to make extra sure it is Ok and then
 260    merged to 'maint'.
 261
 262  * Even when 'next' becomes empty (in other words, all topics
 263    prove stable and are merged to 'master' and "git diff master
 264    next" shows empty), it has tons of merge commits that will
 265    never be in 'master'.
 266
 267  * In principle, "git log --first-parent master..next" should
 268    show nothing but merges (in practice, there are fixup commits
 269    and reverts that are not merges).
 270
 271  * Commits near the tip of a topic branch that are not in 'next'
 272    are fair game to be discarded, replaced or rewritten.
 273    Commits already merged to 'next' will not be.
 274
 275  * Being in the 'next' branch is not a guarantee for a topic to
 276    be included in the next feature release.  Being in the
 277    'master' branch typically is.