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