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/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 246Some 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.