| blob | d527b307707c676e82a08f18cb9fdd7d3abcb228 |
1 From: Junio C Hamano <gitster@pobox.com>
2 Date: Wed, 21 Nov 2007 16:32:55 -0800
3 Subject: Addendum to "MaintNotes"
4 Abstract: 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.
9 The maintainer's git time is spent on three activities.
11 - Communication (60%)
13 Mailing list discussions on general design, fielding user
14 questions, diagnosing bug reports; reviewing, commenting on,
15 suggesting alternatives to, and rejecting patches.
17 - Integration (30%)
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.
24 - Own development (10%)
26 Scratching my own itch and sending proposed patch series out.
28 The policy on Integration is informally mentioned in "A Note
29 from the maintainer" message, which is periodically posted to
30 this mailing list after each feature release is made.
32 The policy.
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.
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).
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.
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.
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'.
58 - 'pu' branch is used to publish other proposed changes that do
59 not yet pass the criteria set for 'next'.
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.
65 - Usually 'master' contains all of 'maint', 'next' contains all
66 of 'master' and 'pu' contains all of 'next'.
68 - The tip of 'master' is meant to be more stable than any
69 tagged releases, and the users are encouraged to follow it.
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'.
76 A typical git day for the maintainer implements the above policy
77 by doing the following:
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).
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.
90 - Classify the collected patches and handle 'master' and
91 'maint' updates:
93 - Obviously correct fixes that pertain to the tip of 'maint'
94 are directly applied to 'maint'.
96 - Obviously correct fixes that pertain to the tip of 'master'
97 are directly applied to 'master'.
99 This step is done with "git am".
101 $ git checkout master ;# or "git checkout maint"
102 $ git am -3 -s mailbox
103 $ make test
105 - Merge downwards (maint->master):
107 $ git checkout master
108 $ git merge maint
109 $ make test
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.
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"
122 - Merge downwards (maint->master) if needed:
124 $ git checkout master
125 $ git merge maint
126 $ make test
128 - Merge downwards (master->next) if needed:
130 $ git checkout next
131 $ git merge master
132 $ make test
134 - Handle the remaining patches:
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").
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.
149 - Changes that pertain to an existing topic are applied to
150 the branch, but:
152 - obviously correct ones are applied first;
154 - questionable ones are discarded or applied to near the tip;
156 - Replacement patches to an existing topic are accepted only
157 for commits not in 'next'.
159 The above except the "replacement" are all done with:
161 $ git am -3 -s mailbox
163 while patch replacement is often done by:
165 $ git format-patch ai/topic~$n..ai/topic ;# export existing
167 then replace some parts with the new patch, and reapplying:
169 $ git reset --hard ai/topic~$n
170 $ git am -3 -s 000*.txt
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.
176 - Update "What's cooking" message to review the updates to
177 existing topics, newly added topics and graduated topics.
179 This step is helped with Meta/UWC script (where Meta/ contains
180 a checkout of the 'todo' branch).
182 - Merge topics to 'next'. For each branch whose tip is not
183 merged to 'next', one of three things can happen:
185 - The commits are all next-worthy; merge the topic to next:
187 $ git checkout next
188 $ git merge ai/topic ;# or "git merge ai/maint-topic"
189 $ make test
191 - The new parts are of mixed quality, but earlier ones are
192 next-worthy; merge the early parts to next:
194 $ git checkout next
195 $ git merge ai/topic~2 ;# the tip two are dubious
196 $ make test
198 - Nothing is next-worthy; do not do anything.
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.
205 $ git rebase master ai/topic
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.
212 - Rebuild "pu" to merge the tips of topics not in 'next'.
214 $ git checkout pu
215 $ git reset --hard next
216 $ git merge ai/topic ;# repeat for all remaining topics
217 $ make test
219 This step is helped with Meta/PU script
221 - Push four integration branches to a private repository at
222 k.org and run "make test" on all of them.
224 - Push four integration branches to /pub/scm/git/git.git at
225 k.org. This triggers its post-update hook which:
227 (1) runs "git pull" in $HOME/git-doc/ repository to pull
228 'master' just pushed out;
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.
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.
239 (4) installs generated documentation to /pub/software/scm/git/docs/
240 to be viewed from http://www.kernel.org/
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
247 Some observations to be made.
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'.
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.
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'.
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'.
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).
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.
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.