]>
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 | ||
31e7bded JH |
42 | - Feature releases are numbered as vX.Y.Z and are meant to |
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 | ||
31e7bded JH |
49 | - Maintenance releases are numbered as vX.Y.Z.W and are meant |
50 | to contain only bugfixes for the corresponding vX.Y.Z feature | |
51 | release and earlier maintenance releases vX.Y.Z.V (V < W). | |
52 | ||
53 | - 'master' branch is used to prepare for the next feature | |
54 | release. In other words, at some point, the tip of 'master' | |
55 | branch is tagged with vX.Y.Z. | |
56 | ||
57 | - 'maint' branch is used to prepare for the next maintenance | |
58 | release. After the feature release vX.Y.Z is made, the tip | |
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 | |
61 | branch is tagged with vX.Y.Z.1, vX.Y.Z.2, and so on. | |
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 | ||
69 | - 'pu' branch is used to publish other proposed changes that do | |
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 JH |
78 | - Usually 'master' contains all of 'maint' and 'next' contains all |
79 | of 'master'. 'pu' contains all the topics merged to 'next', but | |
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 | ||
89 | ||
ab05d7c7 JH |
90 | A Typical Git Day |
91 | ----------------- | |
92 | ||
2de9b711 | 93 | A typical Git day for the maintainer implements the above policy |
31e7bded JH |
94 | by doing the following: |
95 | ||
cc1b258e JH |
96 | - Scan mailing list. Respond with review comments, suggestions |
97 | etc. Kibitz. Collect potentially usable patches from the | |
98 | mailing list. Patches about a single topic go to one mailbox (I | |
99 | read my mail in Gnus, and type \C-o to save/append messages in | |
100 | files in mbox format). | |
101 | ||
102 | - Write his own patches to address issues raised on the list but | |
103 | nobody has stepped up solving. Send it out just like other | |
104 | contributors do, and pick them up just like patches from other | |
105 | contributors (see above). | |
31e7bded JH |
106 | |
107 | - Review the patches in the saved mailboxes. Edit proposed log | |
108 | message for typofixes and clarifications, and add Acks | |
109 | collected from the list. Edit patch to incorporate "Oops, | |
110 | that should have been like this" fixes from the discussion. | |
111 | ||
112 | - Classify the collected patches and handle 'master' and | |
113 | 'maint' updates: | |
114 | ||
115 | - Obviously correct fixes that pertain to the tip of 'maint' | |
116 | are directly applied to 'maint'. | |
117 | ||
118 | - Obviously correct fixes that pertain to the tip of 'master' | |
119 | are directly applied to 'master'. | |
120 | ||
cc1b258e JH |
121 | - Other topics are not handled in this step. |
122 | ||
31e7bded JH |
123 | This step is done with "git am". |
124 | ||
125 | $ git checkout master ;# or "git checkout maint" | |
cc1b258e | 126 | $ git am -sc3 mailbox |
31e7bded JH |
127 | $ make test |
128 | ||
cc1b258e JH |
129 | In practice, almost no patch directly goes to 'master' or |
130 | 'maint'. | |
31e7bded JH |
131 | |
132 | - Review the last issue of "What's cooking" message, review the | |
cc1b258e JH |
133 | topics ready for merging (topic->master and topic->maint). Use |
134 | "Meta/cook -w" script (where Meta/ contains a checkout of the | |
135 | 'todo' branch) to aid this step. | |
136 | ||
137 | And perform the merge. Use "Meta/Reintegrate -e" script (see | |
138 | later) to aid this step. | |
139 | ||
140 | $ Meta/cook -w last-issue-of-whats-cooking.mbox | |
31e7bded JH |
141 | |
142 | $ git checkout master ;# or "git checkout maint" | |
cc1b258e | 143 | $ echo ai/topic | Meta/Reintegrate -e ;# "git merge ai/topic" |
31e7bded JH |
144 | $ git log -p ORIG_HEAD.. ;# final review |
145 | $ git diff ORIG_HEAD.. ;# final review | |
146 | $ make test ;# final review | |
31e7bded JH |
147 | |
148 | - Handle the remaining patches: | |
149 | ||
150 | - Anything unobvious that is applicable to 'master' (in other | |
151 | words, does not depend on anything that is still in 'next' | |
152 | and not in 'master') is applied to a new topic branch that | |
153 | is forked from the tip of 'master'. This includes both | |
154 | enhancements and unobvious fixes to 'master'. A topic | |
cc1b258e JH |
155 | branch is named as ai/topic where "ai" is two-letter string |
156 | named after author's initial and "topic" is a descriptive name | |
157 | of the topic (in other words, "what's the series is about"). | |
31e7bded JH |
158 | |
159 | - An unobvious fix meant for 'maint' is applied to a new | |
160 | topic branch that is forked from the tip of 'maint'. The | |
161 | topic is named as ai/maint-topic. | |
162 | ||
163 | - Changes that pertain to an existing topic are applied to | |
164 | the branch, but: | |
165 | ||
166 | - obviously correct ones are applied first; | |
167 | ||
168 | - questionable ones are discarded or applied to near the tip; | |
169 | ||
170 | - Replacement patches to an existing topic are accepted only | |
171 | for commits not in 'next'. | |
172 | ||
173 | The above except the "replacement" are all done with: | |
174 | ||
cc1b258e JH |
175 | $ git checkout ai/topic ;# or "git checkout -b ai/topic master" |
176 | $ git am -sc3 mailbox | |
31e7bded JH |
177 | |
178 | while patch replacement is often done by: | |
179 | ||
180 | $ git format-patch ai/topic~$n..ai/topic ;# export existing | |
181 | ||
182 | then replace some parts with the new patch, and reapplying: | |
183 | ||
cc1b258e | 184 | $ git checkout ai/topic |
31e7bded | 185 | $ git reset --hard ai/topic~$n |
cc1b258e | 186 | $ git am -sc3 -s 000*.txt |
31e7bded JH |
187 | |
188 | The full test suite is always run for 'maint' and 'master' | |
189 | after patch application; for topic branches the tests are run | |
190 | as time permits. | |
191 | ||
cc1b258e | 192 | - Merge maint to master as needed: |
31e7bded | 193 | |
cc1b258e JH |
194 | $ git checkout master |
195 | $ git merge maint | |
196 | $ make test | |
31e7bded | 197 | |
cc1b258e | 198 | - Merge master to next as needed: |
31e7bded JH |
199 | |
200 | $ git checkout next | |
cc1b258e | 201 | $ git merge master |
31e7bded JH |
202 | $ make test |
203 | ||
cc1b258e JH |
204 | - Review the last issue of "What's cooking" again and see if topics |
205 | that are ready to be merged to 'next' are still in good shape | |
206 | (e.g. has there any new issue identified on the list with the | |
207 | series?) | |
208 | ||
209 | - Prepare 'jch' branch, which is used to represent somewhere | |
210 | between 'master' and 'pu' and often is slightly ahead of 'next'. | |
211 | ||
212 | $ Meta/Reintegrate master..pu >Meta/redo-jch.sh | |
213 | ||
214 | The result is a script that lists topics to be merged in order to | |
215 | rebuild 'pu' as the input to Meta/Reintegrate script. Remove | |
216 | later topics that should not be in 'jch' yet. Add a line that | |
e510f2d6 JH |
217 | consists of '### match next' before the name of the first topic |
218 | in the output that should be in 'jch' but not in 'next' yet. | |
cc1b258e JH |
219 | |
220 | - Now we are ready to start merging topics to 'next'. For each | |
221 | branch whose tip is not merged to 'next', one of three things can | |
222 | happen: | |
223 | ||
224 | - The commits are all next-worthy; merge the topic to next; | |
31e7bded | 225 | - The new parts are of mixed quality, but earlier ones are |
cc1b258e JH |
226 | next-worthy; merge the early parts to next; |
227 | - Nothing is next-worthy; do not do anything. | |
228 | ||
229 | This step is aided with Meta/redo-jch.sh script created earlier. | |
230 | If a topic that was already in 'next' gained a patch, the script | |
231 | would list it as "ai/topic~1". To include the new patch to the | |
232 | updated 'next', drop the "~1" part; to keep it excluded, do not | |
233 | touch the line. If a topic that was not in 'next' should be | |
234 | merged to 'next', add it at the end of the list. Then: | |
235 | ||
236 | $ git checkout -B jch master | |
237 | $ Meta/redo-jch.sh -c1 | |
238 | ||
239 | to rebuild the 'jch' branch from scratch. "-c1" tells the script | |
e510f2d6 JH |
240 | to stop merging at the first line that begins with '###' |
241 | (i.e. the "### match next" line you added earlier). | |
cc1b258e JH |
242 | |
243 | At this point, build-test the result. It may reveal semantic | |
244 | conflicts (e.g. a topic renamed a variable, another added a new | |
245 | reference to the variable under its old name), in which case | |
246 | prepare an appropriate merge-fix first (see appendix), and | |
247 | rebuild the 'jch' branch from scratch, starting at the tip of | |
248 | 'master'. | |
249 | ||
250 | Then do the same to 'next' | |
31e7bded JH |
251 | |
252 | $ git checkout next | |
cc1b258e | 253 | $ sh Meta/redo-jch.sh -c1 -e |
31e7bded | 254 | |
cc1b258e JH |
255 | The "-e" option allows the merge message that comes from the |
256 | history of the topic and the comments in the "What's cooking" to | |
257 | be edited. The resulting tree should match 'jch' as the same set | |
258 | of topics are merged on 'master'; otherwise there is a mismerge. | |
259 | Investigate why and do not proceed until the mismerge is found | |
260 | and rectified. | |
31e7bded | 261 | |
cc1b258e | 262 | $ git diff jch next |
31e7bded | 263 | |
cc1b258e | 264 | When all is well, clean up the redo-jch.sh script with |
31e7bded | 265 | |
cc1b258e | 266 | $ sh Meta/redo-jch.sh -u |
31e7bded | 267 | |
cc1b258e | 268 | This removes topics listed in the script that have already been |
e510f2d6 JH |
269 | merged to 'master'. This may lose '### match next' marker; |
270 | add it again to the appropriate place when it happens. | |
31e7bded | 271 | |
cc1b258e | 272 | - Rebuild 'pu'. |
31e7bded | 273 | |
cc1b258e | 274 | $ Meta/Reintegrate master..pu >Meta/redo-pu.sh |
31e7bded | 275 | |
cc1b258e JH |
276 | Edit the result by adding new topics that are not still in 'pu' |
277 | in the script. Then | |
31e7bded | 278 | |
cc1b258e JH |
279 | $ git checkout -B pu jch |
280 | $ sh Meta/redo-pu.sh | |
31e7bded | 281 | |
cc1b258e | 282 | When all is well, clean up the redo-pu.sh script with |
31e7bded | 283 | |
cc1b258e | 284 | $ sh Meta/redo-pu.sh -u |
31e7bded | 285 | |
cc1b258e | 286 | Double check by running |
31e7bded | 287 | |
cc1b258e | 288 | $ git branch --no-merged pu |
31e7bded | 289 | |
cc1b258e | 290 | to see there is no unexpected leftover topics. |
31e7bded | 291 | |
cc1b258e JH |
292 | At this point, build-test the result for semantic conflicts, and |
293 | if there are, prepare an appropriate merge-fix first (see | |
294 | appendix), and rebuild the 'pu' branch from scratch, starting at | |
295 | the tip of 'jch'. | |
31e7bded | 296 | |
cc1b258e JH |
297 | - Update "What's cooking" message to review the updates to |
298 | existing topics, newly added topics and graduated topics. | |
299 | ||
300 | This step is helped with Meta/cook script. | |
301 | ||
302 | $ Meta/cook | |
303 | ||
304 | This script inspects the history between master..pu, finds tips | |
305 | of topic branches, compares what it found with the current | |
306 | contents in Meta/whats-cooking.txt, and updates that file. | |
307 | Topics not listed in the file but are found in master..pu are | |
308 | added to the "New topics" section, topics listed in the file that | |
309 | are no longer found in master..pu are moved to the "Graduated to | |
310 | master" section, and topics whose commits changed their states | |
311 | (e.g. used to be only in 'pu', now merged to 'next') are updated | |
312 | with change markers "<<" and ">>". | |
31e7bded | 313 | |
cc1b258e JH |
314 | Look for lines enclosed in "<<" and ">>"; they hold contents from |
315 | old file that are replaced by this integration round. After | |
316 | verifying them, remove the old part. Review the description for | |
317 | each topic and update its doneness and plan as needed. To review | |
318 | the updated plan, run | |
31e7bded | 319 | |
cc1b258e | 320 | $ Meta/cook -w |
31e7bded | 321 | |
cc1b258e JH |
322 | which will pick up comments given to the topics, such as "Will |
323 | merge to 'next'", etc. (see Meta/cook script to learn what kind | |
324 | of phrases are supported). | |
325 | ||
326 | - Compile, test and install all four (five) integration branches; | |
327 | Meta/Dothem script may aid this step. | |
328 | ||
329 | - Format documentation if the 'master' branch was updated; | |
330 | Meta/dodoc.sh script may aid this step. | |
331 | ||
332 | - Push the integration branches out to public places; Meta/pushall | |
333 | script may aid this step. | |
31e7bded | 334 | |
ab05d7c7 JH |
335 | Observations |
336 | ------------ | |
31e7bded JH |
337 | |
338 | Some observations to be made. | |
339 | ||
cc1b258e JH |
340 | * Each topic is tested individually, and also together with other |
341 | topics cooking first in 'pu', then in 'jch' and then in 'next'. | |
342 | Until it matures, no part of it is merged to 'master'. | |
31e7bded JH |
343 | |
344 | * A topic already in 'next' can get fixes while still in | |
345 | 'next'. Such a topic will have many merges to 'next' (in | |
346 | other words, "git log --first-parent next" will show many | |
cc1b258e | 347 | "Merge branch 'ai/topic' to next" for the same topic. |
31e7bded JH |
348 | |
349 | * An unobvious fix for 'maint' is cooked in 'next' and then | |
350 | merged to 'master' to make extra sure it is Ok and then | |
351 | merged to 'maint'. | |
352 | ||
353 | * Even when 'next' becomes empty (in other words, all topics | |
354 | prove stable and are merged to 'master' and "git diff master | |
355 | next" shows empty), it has tons of merge commits that will | |
356 | never be in 'master'. | |
357 | ||
358 | * In principle, "git log --first-parent master..next" should | |
359 | show nothing but merges (in practice, there are fixup commits | |
360 | and reverts that are not merges). | |
361 | ||
362 | * Commits near the tip of a topic branch that are not in 'next' | |
363 | are fair game to be discarded, replaced or rewritten. | |
364 | Commits already merged to 'next' will not be. | |
365 | ||
366 | * Being in the 'next' branch is not a guarantee for a topic to | |
367 | be included in the next feature release. Being in the | |
368 | 'master' branch typically is. | |
cc1b258e JH |
369 | |
370 | ||
ab05d7c7 JH |
371 | Appendix |
372 | -------- | |
cc1b258e JH |
373 | |
374 | Preparing a "merge-fix" | |
ab05d7c7 | 375 | ~~~~~~~~~~~~~~~~~~~~~~~ |
cc1b258e JH |
376 | |
377 | A merge of two topics may not textually conflict but still have | |
378 | conflict at the semantic level. A classic example is for one topic | |
379 | to rename an variable and all its uses, while another topic adds a | |
380 | new use of the variable under its old name. When these two topics | |
381 | are merged together, the reference to the variable newly added by | |
382 | the latter topic will still use the old name in the result. | |
383 | ||
384 | The Meta/Reintegrate script that is used by redo-jch and redo-pu | |
385 | scripts implements a crude but usable way to work this issue around. | |
386 | When the script merges branch $X, it checks if "refs/merge-fix/$X" | |
387 | exists, and if so, the effect of it is squashed into the result of | |
388 | the mechanical merge. In other words, | |
389 | ||
390 | $ echo $X | Meta/Reintegrate | |
391 | ||
392 | is roughly equivalent to this sequence: | |
393 | ||
394 | $ git merge --rerere-autoupdate $X | |
395 | $ git commit | |
396 | $ git cherry-pick -n refs/merge-fix/$X | |
397 | $ git commit --amend | |
398 | ||
399 | The goal of this "prepare a merge-fix" step is to come up with a | |
400 | commit that can be squashed into a result of mechanical merge to | |
401 | correct semantic conflicts. | |
402 | ||
403 | After finding that the result of merging branch "ai/topic" to an | |
404 | integration branch had such a semantic conflict, say pu~4, check the | |
405 | problematic merge out on a detached HEAD, edit the working tree to | |
406 | fix the semantic conflict, and make a separate commit to record the | |
407 | fix-up: | |
408 | ||
409 | $ git checkout pu~4 | |
410 | $ git show -s --pretty=%s ;# double check | |
411 | Merge branch 'ai/topic' to pu | |
412 | $ edit | |
413 | $ git commit -m 'merge-fix/ai/topic' -a | |
414 | ||
415 | Then make a reference "refs/merge-fix/ai/topic" to point at this | |
416 | result: | |
417 | ||
418 | $ git update-ref refs/merge-fix/ai/topic HEAD | |
419 | ||
420 | Then double check the result by asking Meta/Reintegrate to redo the | |
421 | merge: | |
422 | ||
423 | $ git checkout pu~5 ;# the parent of the problem merge | |
424 | $ echo ai/topic | Meta/Reintegrate | |
425 | $ git diff pu~4 | |
426 | ||
427 | This time, because you prepared refs/merge-fix/ai/topic, the | |
428 | resulting merge should have been tweaked to include the fix for the | |
429 | semantic conflict. | |
430 | ||
431 | Note that this assumes that the order in which conflicting branches | |
432 | are merged does not change. If the reason why merging ai/topic | |
433 | branch needs this merge-fix is because another branch merged earlier | |
434 | to the integration branch changed the underlying assumption ai/topic | |
435 | branch made (e.g. ai/topic branch added a site to refer to a | |
436 | variable, while the other branch renamed that variable and adjusted | |
437 | existing use sites), and if you changed redo-jch (or redo-pu) script | |
438 | to merge ai/topic branch before the other branch, then the above | |
439 | merge-fix should not be applied while merging ai/topic, but should | |
440 | instead be applied while merging the other branch. You would need | |
441 | to move the fix to apply to the other branch, perhaps like this: | |
442 | ||
443 | $ mf=refs/merge-fix | |
444 | $ git update-ref $mf/$the_other_branch $mf/ai/topic | |
445 | $ git update-ref -d $mf/ai/topic |