@matheusbsbs / matheus-bagliano / commits / 31e7bded60
Fork 0

Addendum to "MaintNotes"

Add "how to maintain git" document. Foreward by Jeff King. Signed-off-by: Junio C Hamano <gitster@pobox.com>

Junio C Hamano committed Nov 22, 2007 at 06:08 UTC 31e7bded608416e3116f9c691a4d4314f10640b6
1 file changed +277
Documentation/howto/maintain-git.txt new
+277
@@ -0,0 +1,277 @@
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.
8 +
9 +The 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 +
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.
31 +
32 +The 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 +
76 +A typical git day for the maintainer implements the above policy
77 +by 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/UWC 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 + - 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.
204 +
205 + $ git rebase master ai/topic
206 +
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.
211 +
212 + - Rebuild "pu" to merge the tips of topics not in 'next'.
213 +
214 + $ git checkout pu
215 + $ git reset --hard next
216 + $ git merge ai/topic ;# repeat for all remaining topics
217 + $ make test
218 +
219 + This step is helped with Meta/PU script
220 +
221 + - Push four integration branches to a private repository at
222 + k.org and run "make test" on all of them.
223 +
224 + - Push four integration branches to /pub/scm/git/git.git at
225 + k.org. This triggers its post-update hook which:
226 +
227 + (1) runs "git pull" in $HOME/git-doc/ repository to pull
228 + 'master' just pushed out;
229 +
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.
234 +
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.
238 +
239 + (4) installs generated documentation to /pub/software/scm/git/docs/
240 + to be viewed from http://www.kernel.org/
241 +
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
245 +
246 +
247 +Some observations to be made.
248 +
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'.
252 +
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.
257 +
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'.
261 +
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'.
266 +
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).
270 +
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.
274 +
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.