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