]>
Commit | Line | Data |
---|---|---|
31e7bded JH |
1 | From: Junio C Hamano <gitster@pobox.com> |
2 | Date: Wed, 21 Nov 2007 16:32:55 -0800 | |
3 | Subject: Addendum to "MaintNotes" | |
2de9b711 | 4 | Abstract: Imagine that Git development is racing along as usual, when our friendly |
31e7bded JH |
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. | |
1797e5c5 TA |
8 | Content-type: text/asciidoc |
9 | ||
10 | How to maintain Git | |
11 | =================== | |
31e7bded | 12 | |
ab05d7c7 JH |
13 | Activities |
14 | ---------- | |
15 | ||
2de9b711 | 16 | The maintainer's Git time is spent on three activities. |
31e7bded | 17 | |
cc1b258e | 18 | - Communication (45%) |
31e7bded JH |
19 | |
20 | Mailing list discussions on general design, fielding user | |
21 | questions, diagnosing bug reports; reviewing, commenting on, | |
22 | suggesting alternatives to, and rejecting patches. | |
23 | ||
cc1b258e | 24 | - Integration (50%) |
31e7bded JH |
25 | |
26 | Applying new patches from the contributors while spotting and | |
27 | correcting minor mistakes, shuffling the integration and | |
28 | testing branches, pushing the results out, cutting the | |
29 | releases, and making announcements. | |
30 | ||
cc1b258e | 31 | - Own development (5%) |
31e7bded JH |
32 | |
33 | Scratching my own itch and sending proposed patch series out. | |
34 | ||
ab05d7c7 JH |
35 | The Policy |
36 | ---------- | |
37 | ||
31e7bded JH |
38 | The policy on Integration is informally mentioned in "A Note |
39 | from the maintainer" message, which is periodically posted to | |
40 | this mailing list after each feature release is made. | |
41 | ||
c7b8cf49 | 42 | - Feature releases are numbered as vX.Y.0 and are meant to |
31e7bded JH |
43 | contain bugfixes and enhancements in any area, including |
44 | functionality, performance and usability, without regression. | |
45 | ||
cc1b258e JH |
46 | - One release cycle for a feature release is expected to last for |
47 | eight to ten weeks. | |
48 | ||
c7b8cf49 JH |
49 | - Maintenance releases are numbered as vX.Y.Z and are meant |
50 | to contain only bugfixes for the corresponding vX.Y.0 feature | |
51 | release and earlier maintenance releases vX.Y.W (W < Z). | |
31e7bded JH |
52 | |
53 | - 'master' branch is used to prepare for the next feature | |
54 | release. In other words, at some point, the tip of 'master' | |
c7b8cf49 | 55 | branch is tagged with vX.Y.0. |
31e7bded JH |
56 | |
57 | - 'maint' branch is used to prepare for the next maintenance | |
c7b8cf49 | 58 | release. After the feature release vX.Y.0 is made, the tip |
31e7bded JH |
59 | of 'maint' branch is set to that release, and bugfixes will |
60 | accumulate on the branch, and at some point, the tip of the | |
c7b8cf49 | 61 | branch is tagged with vX.Y.1, vX.Y.2, and so on. |
31e7bded JH |
62 | |
63 | - 'next' branch is used to publish changes (both enhancements | |
64 | and fixes) that (1) have worthwhile goal, (2) are in a fairly | |
65 | good shape suitable for everyday use, (3) but have not yet | |
66 | demonstrated to be regression free. New changes are tested | |
67 | in 'next' before merged to 'master'. | |
68 | ||
77dc6049 | 69 | - 'seen' branch is used to publish other proposed changes that do |
31e7bded JH |
70 | not yet pass the criteria set for 'next'. |
71 | ||
cc1b258e JH |
72 | - The tips of 'master' and 'maint' branches will not be rewound to |
73 | allow people to build their own customization on top of them. | |
74 | Early in a new development cycle, 'next' is rewound to the tip of | |
75 | 'master' once, but otherwise it will not be rewound until the end | |
76 | of the cycle. | |
31e7bded | 77 | |
cc1b258e | 78 | - Usually 'master' contains all of 'maint' and 'next' contains all |
77dc6049 | 79 | of 'master'. 'seen' contains all the topics merged to 'next', but |
cc1b258e | 80 | is rebuilt directly on 'master'. |
31e7bded JH |
81 | |
82 | - The tip of 'master' is meant to be more stable than any | |
83 | tagged releases, and the users are encouraged to follow it. | |
84 | ||
85 | - The 'next' branch is where new action takes place, and the | |
86 | users are encouraged to test it so that regressions and bugs | |
87 | are found before new topics are merged to 'master'. | |
88 | ||
c7b8cf49 JH |
89 | Note that before v1.9.0 release, the version numbers used to be |
90 | structured slightly differently. vX.Y.Z were feature releases while | |
91 | vX.Y.Z.W were maintenance releases for vX.Y.Z. | |
92 | ||
31e7bded | 93 | |
ab05d7c7 JH |
94 | A Typical Git Day |
95 | ----------------- | |
96 | ||
2de9b711 | 97 | A typical Git day for the maintainer implements the above policy |
31e7bded JH |
98 | by doing the following: |
99 | ||
cc1b258e JH |
100 | - Scan mailing list. Respond with review comments, suggestions |
101 | etc. Kibitz. Collect potentially usable patches from the | |
102 | mailing list. Patches about a single topic go to one mailbox (I | |
103 | read my mail in Gnus, and type \C-o to save/append messages in | |
104 | files in mbox format). | |
105 | ||
106 | - Write his own patches to address issues raised on the list but | |
cf6cac20 | 107 | nobody has stepped up to solve. Send it out just like other |
cc1b258e JH |
108 | contributors do, and pick them up just like patches from other |
109 | contributors (see above). | |
31e7bded JH |
110 | |
111 | - Review the patches in the saved mailboxes. Edit proposed log | |
112 | message for typofixes and clarifications, and add Acks | |
113 | collected from the list. Edit patch to incorporate "Oops, | |
114 | that should have been like this" fixes from the discussion. | |
115 | ||
116 | - Classify the collected patches and handle 'master' and | |
117 | 'maint' updates: | |
118 | ||
119 | - Obviously correct fixes that pertain to the tip of 'maint' | |
120 | are directly applied to 'maint'. | |
121 | ||
122 | - Obviously correct fixes that pertain to the tip of 'master' | |
123 | are directly applied to 'master'. | |
124 | ||
cc1b258e JH |
125 | - Other topics are not handled in this step. |
126 | ||
31e7bded JH |
127 | This step is done with "git am". |
128 | ||
129 | $ git checkout master ;# or "git checkout maint" | |
cc1b258e | 130 | $ git am -sc3 mailbox |
31e7bded JH |
131 | $ make test |
132 | ||
cc1b258e JH |
133 | In practice, almost no patch directly goes to 'master' or |
134 | 'maint'. | |
31e7bded JH |
135 | |
136 | - Review the last issue of "What's cooking" message, review the | |
cc1b258e JH |
137 | topics ready for merging (topic->master and topic->maint). Use |
138 | "Meta/cook -w" script (where Meta/ contains a checkout of the | |
139 | 'todo' branch) to aid this step. | |
140 | ||
141 | And perform the merge. Use "Meta/Reintegrate -e" script (see | |
142 | later) to aid this step. | |
143 | ||
144 | $ Meta/cook -w last-issue-of-whats-cooking.mbox | |
31e7bded JH |
145 | |
146 | $ git checkout master ;# or "git checkout maint" | |
cc1b258e | 147 | $ echo ai/topic | Meta/Reintegrate -e ;# "git merge ai/topic" |
31e7bded JH |
148 | $ git log -p ORIG_HEAD.. ;# final review |
149 | $ git diff ORIG_HEAD.. ;# final review | |
150 | $ make test ;# final review | |
31e7bded JH |
151 | |
152 | - Handle the remaining patches: | |
153 | ||
154 | - Anything unobvious that is applicable to 'master' (in other | |
155 | words, does not depend on anything that is still in 'next' | |
156 | and not in 'master') is applied to a new topic branch that | |
564956f3 JH |
157 | is forked from the tip of 'master' (or the last feature release, |
158 | which is a bit older than 'master'). This includes both | |
31e7bded | 159 | enhancements and unobvious fixes to 'master'. A topic |
cc1b258e JH |
160 | branch is named as ai/topic where "ai" is two-letter string |
161 | named after author's initial and "topic" is a descriptive name | |
162 | of the topic (in other words, "what's the series is about"). | |
31e7bded JH |
163 | |
164 | - An unobvious fix meant for 'maint' is applied to a new | |
564956f3 JH |
165 | topic branch that is forked from the tip of 'maint' (or the |
166 | oldest and still relevant maintenance branch). The | |
167 | topic may be named as ai/maint-topic. | |
31e7bded JH |
168 | |
169 | - Changes that pertain to an existing topic are applied to | |
170 | the branch, but: | |
171 | ||
172 | - obviously correct ones are applied first; | |
173 | ||
174 | - questionable ones are discarded or applied to near the tip; | |
175 | ||
176 | - Replacement patches to an existing topic are accepted only | |
177 | for commits not in 'next'. | |
178 | ||
564956f3 | 179 | The initial round is done with: |
31e7bded | 180 | |
cc1b258e JH |
181 | $ git checkout ai/topic ;# or "git checkout -b ai/topic master" |
182 | $ git am -sc3 mailbox | |
31e7bded | 183 | |
564956f3 | 184 | and replacing an existing topic with subsequent round is done with: |
31e7bded | 185 | |
564956f3 JH |
186 | $ git checkout master...ai/topic ;# try to reapply to the same base |
187 | $ git am -sc3 mailbox | |
188 | ||
189 | to prepare the new round on a detached HEAD, and then | |
190 | ||
191 | $ git range-diff @{-1}... | |
192 | $ git diff @{-1} | |
31e7bded | 193 | |
564956f3 | 194 | to double check what changed since the last round, and finally |
31e7bded | 195 | |
564956f3 JH |
196 | $ git checkout -B @{-1} |
197 | ||
198 | to conclude (the last step is why a topic already in 'next' is | |
199 | not replaced but updated incrementally). | |
200 | ||
201 | Whether it is the initial round or a subsequent round, the topic | |
202 | may not build even in isolation, or may break the build when | |
203 | merged to integration branches due to bugs. There may already | |
204 | be obvious and trivial improvements suggested on the list. The | |
205 | maintainer often adds an extra commit, with "SQUASH???" in its | |
206 | title, to fix things up, before publishing the integration | |
207 | branches to make it usable by other developers for testing. | |
208 | These changes are what the maintainer is not 100% committed to | |
209 | (trivial typofixes etc. are often squashed directly into the | |
210 | patches that need fixing, without being applied as a separate | |
211 | "SQUASH???" commit), so that they can be removed easily as needed. | |
31e7bded | 212 | |
31e7bded | 213 | |
cc1b258e | 214 | - Merge maint to master as needed: |
31e7bded | 215 | |
cc1b258e JH |
216 | $ git checkout master |
217 | $ git merge maint | |
218 | $ make test | |
31e7bded | 219 | |
cc1b258e | 220 | - Merge master to next as needed: |
31e7bded JH |
221 | |
222 | $ git checkout next | |
cc1b258e | 223 | $ git merge master |
31e7bded JH |
224 | $ make test |
225 | ||
cc1b258e JH |
226 | - Review the last issue of "What's cooking" again and see if topics |
227 | that are ready to be merged to 'next' are still in good shape | |
228 | (e.g. has there any new issue identified on the list with the | |
229 | series?) | |
230 | ||
231 | - Prepare 'jch' branch, which is used to represent somewhere | |
77dc6049 | 232 | between 'master' and 'seen' and often is slightly ahead of 'next'. |
cc1b258e | 233 | |
7fa56b1a | 234 | $ Meta/Reintegrate master..jch >Meta/redo-jch.sh |
cc1b258e JH |
235 | |
236 | The result is a script that lists topics to be merged in order to | |
77dc6049 | 237 | rebuild 'seen' as the input to Meta/Reintegrate script. Remove |
cc1b258e | 238 | later topics that should not be in 'jch' yet. Add a line that |
e510f2d6 JH |
239 | consists of '### match next' before the name of the first topic |
240 | in the output that should be in 'jch' but not in 'next' yet. | |
cc1b258e JH |
241 | |
242 | - Now we are ready to start merging topics to 'next'. For each | |
243 | branch whose tip is not merged to 'next', one of three things can | |
244 | happen: | |
245 | ||
246 | - The commits are all next-worthy; merge the topic to next; | |
31e7bded | 247 | - The new parts are of mixed quality, but earlier ones are |
cc1b258e JH |
248 | next-worthy; merge the early parts to next; |
249 | - Nothing is next-worthy; do not do anything. | |
250 | ||
251 | This step is aided with Meta/redo-jch.sh script created earlier. | |
252 | If a topic that was already in 'next' gained a patch, the script | |
253 | would list it as "ai/topic~1". To include the new patch to the | |
254 | updated 'next', drop the "~1" part; to keep it excluded, do not | |
255 | touch the line. If a topic that was not in 'next' should be | |
256 | merged to 'next', add it at the end of the list. Then: | |
257 | ||
258 | $ git checkout -B jch master | |
6c3b077c | 259 | $ sh Meta/redo-jch.sh -c1 |
cc1b258e JH |
260 | |
261 | to rebuild the 'jch' branch from scratch. "-c1" tells the script | |
e510f2d6 JH |
262 | to stop merging at the first line that begins with '###' |
263 | (i.e. the "### match next" line you added earlier). | |
cc1b258e JH |
264 | |
265 | At this point, build-test the result. It may reveal semantic | |
266 | conflicts (e.g. a topic renamed a variable, another added a new | |
267 | reference to the variable under its old name), in which case | |
268 | prepare an appropriate merge-fix first (see appendix), and | |
269 | rebuild the 'jch' branch from scratch, starting at the tip of | |
270 | 'master'. | |
271 | ||
272 | Then do the same to 'next' | |
31e7bded JH |
273 | |
274 | $ git checkout next | |
cc1b258e | 275 | $ sh Meta/redo-jch.sh -c1 -e |
31e7bded | 276 | |
cc1b258e JH |
277 | The "-e" option allows the merge message that comes from the |
278 | history of the topic and the comments in the "What's cooking" to | |
279 | be edited. The resulting tree should match 'jch' as the same set | |
280 | of topics are merged on 'master'; otherwise there is a mismerge. | |
281 | Investigate why and do not proceed until the mismerge is found | |
282 | and rectified. | |
31e7bded | 283 | |
cc1b258e | 284 | $ git diff jch next |
31e7bded | 285 | |
7fa56b1a TB |
286 | Then build the rest of 'jch': |
287 | ||
288 | $ git checkout jch | |
289 | $ sh Meta/redo-jch.sh | |
290 | ||
cc1b258e | 291 | When all is well, clean up the redo-jch.sh script with |
31e7bded | 292 | |
cc1b258e | 293 | $ sh Meta/redo-jch.sh -u |
31e7bded | 294 | |
cc1b258e | 295 | This removes topics listed in the script that have already been |
e510f2d6 JH |
296 | merged to 'master'. This may lose '### match next' marker; |
297 | add it again to the appropriate place when it happens. | |
31e7bded | 298 | |
77dc6049 | 299 | - Rebuild 'seen'. |
31e7bded | 300 | |
c805f06b | 301 | $ Meta/Reintegrate jch..seen >Meta/redo-seen.sh |
31e7bded | 302 | |
77dc6049 | 303 | Edit the result by adding new topics that are not still in 'seen' |
cc1b258e | 304 | in the script. Then |
31e7bded | 305 | |
77dc6049 JS |
306 | $ git checkout -B seen jch |
307 | $ sh Meta/redo-seen.sh | |
31e7bded | 308 | |
77dc6049 | 309 | When all is well, clean up the redo-seen.sh script with |
31e7bded | 310 | |
77dc6049 | 311 | $ sh Meta/redo-seen.sh -u |
31e7bded | 312 | |
cc1b258e | 313 | Double check by running |
31e7bded | 314 | |
77dc6049 | 315 | $ git branch --no-merged seen |
31e7bded | 316 | |
cc1b258e | 317 | to see there is no unexpected leftover topics. |
31e7bded | 318 | |
cc1b258e JH |
319 | At this point, build-test the result for semantic conflicts, and |
320 | if there are, prepare an appropriate merge-fix first (see | |
77dc6049 | 321 | appendix), and rebuild the 'seen' branch from scratch, starting at |
cc1b258e | 322 | the tip of 'jch'. |
31e7bded | 323 | |
cc1b258e JH |
324 | - Update "What's cooking" message to review the updates to |
325 | existing topics, newly added topics and graduated topics. | |
326 | ||
327 | This step is helped with Meta/cook script. | |
328 | ||
329 | $ Meta/cook | |
330 | ||
77dc6049 | 331 | This script inspects the history between master..seen, finds tips |
cc1b258e JH |
332 | of topic branches, compares what it found with the current |
333 | contents in Meta/whats-cooking.txt, and updates that file. | |
77dc6049 | 334 | Topics not listed in the file but are found in master..seen are |
cc1b258e | 335 | added to the "New topics" section, topics listed in the file that |
77dc6049 | 336 | are no longer found in master..seen are moved to the "Graduated to |
cc1b258e | 337 | master" section, and topics whose commits changed their states |
77dc6049 | 338 | (e.g. used to be only in 'seen', now merged to 'next') are updated |
cc1b258e | 339 | with change markers "<<" and ">>". |
31e7bded | 340 | |
cc1b258e JH |
341 | Look for lines enclosed in "<<" and ">>"; they hold contents from |
342 | old file that are replaced by this integration round. After | |
343 | verifying them, remove the old part. Review the description for | |
344 | each topic and update its doneness and plan as needed. To review | |
345 | the updated plan, run | |
31e7bded | 346 | |
cc1b258e | 347 | $ Meta/cook -w |
31e7bded | 348 | |
cc1b258e JH |
349 | which will pick up comments given to the topics, such as "Will |
350 | merge to 'next'", etc. (see Meta/cook script to learn what kind | |
351 | of phrases are supported). | |
352 | ||
353 | - Compile, test and install all four (five) integration branches; | |
354 | Meta/Dothem script may aid this step. | |
355 | ||
356 | - Format documentation if the 'master' branch was updated; | |
357 | Meta/dodoc.sh script may aid this step. | |
358 | ||
359 | - Push the integration branches out to public places; Meta/pushall | |
360 | script may aid this step. | |
31e7bded | 361 | |
ab05d7c7 JH |
362 | Observations |
363 | ------------ | |
31e7bded JH |
364 | |
365 | Some observations to be made. | |
366 | ||
cc1b258e | 367 | * Each topic is tested individually, and also together with other |
77dc6049 | 368 | topics cooking first in 'seen', then in 'jch' and then in 'next'. |
cc1b258e | 369 | Until it matures, no part of it is merged to 'master'. |
31e7bded JH |
370 | |
371 | * A topic already in 'next' can get fixes while still in | |
372 | 'next'. Such a topic will have many merges to 'next' (in | |
373 | other words, "git log --first-parent next" will show many | |
cc1b258e | 374 | "Merge branch 'ai/topic' to next" for the same topic. |
31e7bded JH |
375 | |
376 | * An unobvious fix for 'maint' is cooked in 'next' and then | |
377 | merged to 'master' to make extra sure it is Ok and then | |
378 | merged to 'maint'. | |
379 | ||
380 | * Even when 'next' becomes empty (in other words, all topics | |
381 | prove stable and are merged to 'master' and "git diff master | |
382 | next" shows empty), it has tons of merge commits that will | |
383 | never be in 'master'. | |
384 | ||
385 | * In principle, "git log --first-parent master..next" should | |
386 | show nothing but merges (in practice, there are fixup commits | |
387 | and reverts that are not merges). | |
388 | ||
389 | * Commits near the tip of a topic branch that are not in 'next' | |
390 | are fair game to be discarded, replaced or rewritten. | |
391 | Commits already merged to 'next' will not be. | |
392 | ||
393 | * Being in the 'next' branch is not a guarantee for a topic to | |
394 | be included in the next feature release. Being in the | |
395 | 'master' branch typically is. | |
cc1b258e | 396 | |
564956f3 JH |
397 | * Due to the nature of "SQUASH???" fix-ups, if the original author |
398 | agrees with the suggested changes, it is OK to squash them to | |
399 | appropriate patches in the next round (when the suggested change | |
400 | is small enough, the author should not even bother with | |
401 | "Helped-by"). It is also OK to drop them from the next round | |
402 | when the original author does not agree with the suggestion, but | |
403 | the author is expected to say why somewhere in the discussion. | |
404 | ||
cc1b258e | 405 | |
ab05d7c7 JH |
406 | Appendix |
407 | -------- | |
cc1b258e JH |
408 | |
409 | Preparing a "merge-fix" | |
ab05d7c7 | 410 | ~~~~~~~~~~~~~~~~~~~~~~~ |
cc1b258e JH |
411 | |
412 | A merge of two topics may not textually conflict but still have | |
413 | conflict at the semantic level. A classic example is for one topic | |
3771d002 | 414 | to rename a variable and all its uses, while another topic adds a |
cc1b258e JH |
415 | new use of the variable under its old name. When these two topics |
416 | are merged together, the reference to the variable newly added by | |
417 | the latter topic will still use the old name in the result. | |
418 | ||
77dc6049 | 419 | The Meta/Reintegrate script that is used by redo-jch and redo-seen |
cf6cac20 | 420 | scripts implements a crude but usable way to work around this issue. |
cc1b258e JH |
421 | When the script merges branch $X, it checks if "refs/merge-fix/$X" |
422 | exists, and if so, the effect of it is squashed into the result of | |
423 | the mechanical merge. In other words, | |
424 | ||
425 | $ echo $X | Meta/Reintegrate | |
426 | ||
427 | is roughly equivalent to this sequence: | |
428 | ||
429 | $ git merge --rerere-autoupdate $X | |
430 | $ git commit | |
431 | $ git cherry-pick -n refs/merge-fix/$X | |
432 | $ git commit --amend | |
433 | ||
434 | The goal of this "prepare a merge-fix" step is to come up with a | |
435 | commit that can be squashed into a result of mechanical merge to | |
436 | correct semantic conflicts. | |
437 | ||
438 | After finding that the result of merging branch "ai/topic" to an | |
77dc6049 | 439 | integration branch had such a semantic conflict, say seen~4, check the |
cc1b258e JH |
440 | problematic merge out on a detached HEAD, edit the working tree to |
441 | fix the semantic conflict, and make a separate commit to record the | |
442 | fix-up: | |
443 | ||
77dc6049 | 444 | $ git checkout seen~4 |
cc1b258e | 445 | $ git show -s --pretty=%s ;# double check |
77dc6049 | 446 | Merge branch 'ai/topic' to seen |
cc1b258e JH |
447 | $ edit |
448 | $ git commit -m 'merge-fix/ai/topic' -a | |
449 | ||
450 | Then make a reference "refs/merge-fix/ai/topic" to point at this | |
451 | result: | |
452 | ||
453 | $ git update-ref refs/merge-fix/ai/topic HEAD | |
454 | ||
455 | Then double check the result by asking Meta/Reintegrate to redo the | |
456 | merge: | |
457 | ||
77dc6049 | 458 | $ git checkout seen~5 ;# the parent of the problem merge |
cc1b258e | 459 | $ echo ai/topic | Meta/Reintegrate |
77dc6049 | 460 | $ git diff seen~4 |
cc1b258e JH |
461 | |
462 | This time, because you prepared refs/merge-fix/ai/topic, the | |
463 | resulting merge should have been tweaked to include the fix for the | |
464 | semantic conflict. | |
465 | ||
466 | Note that this assumes that the order in which conflicting branches | |
467 | are merged does not change. If the reason why merging ai/topic | |
468 | branch needs this merge-fix is because another branch merged earlier | |
469 | to the integration branch changed the underlying assumption ai/topic | |
470 | branch made (e.g. ai/topic branch added a site to refer to a | |
471 | variable, while the other branch renamed that variable and adjusted | |
77dc6049 | 472 | existing use sites), and if you changed redo-jch (or redo-seen) script |
cc1b258e JH |
473 | to merge ai/topic branch before the other branch, then the above |
474 | merge-fix should not be applied while merging ai/topic, but should | |
475 | instead be applied while merging the other branch. You would need | |
476 | to move the fix to apply to the other branch, perhaps like this: | |
477 | ||
478 | $ mf=refs/merge-fix | |
479 | $ git update-ref $mf/$the_other_branch $mf/ai/topic | |
480 | $ git update-ref -d $mf/ai/topic |