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. 8 9The 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 28The policy on Integration is informally mentioned in "A Note 29from the maintainer" message, which is periodically posted to 30this mailing list after each feature release is made. 31 32The 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 76A typical git day for the maintainer implements the above policy 77by 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 247Some 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.