@@ -8,53 +8,71 @@ project. There is also a link:MyFirstContribution.html[step-by-step tutorial]
8
8
available which covers many of these same guidelines.
9
9
10
10
[[patch-flow]]
11
- === An ideal patch flow
11
+ === A typical life cycle of a patch series
12
12
13
- Here is an ideal patch flow for this project the current maintainer
14
- suggests to the contributors:
13
+ To help us understand the reason behind various guidelines given later
14
+ in the document, first let's understand how the life cycle of a
15
+ typical patch series for this project goes.
15
16
16
- . You come up with an itch. You code it up.
17
-
18
- . Send it to the list and cc people who may need to know about
19
- the change.
17
+ . You come up with an itch. You code it up. You do not need any
18
+ pre-authorization from the project to do so.
19
+ +
20
+ Your patches will be reviewed by other contributors on the mailing
21
+ list, and the reviews will be done to assess the merit of various
22
+ things, like the general idea behind your patch (including "is it
23
+ solving a problem worth solving in the first place?"), the reason
24
+ behind the design of the solution, and the actual implementation.
25
+ The guidelines given here are there to help your patches by making
26
+ them easier to understand by the reviewers.
27
+
28
+ . You send the patches to the list and cc people who may need to know
29
+ about the change. Your goal is *not* necessarily to convince others
30
+ that what you are building is good. Your goal is to get help in
31
+ coming up with a solution for the "itch" that is better than what
32
+ you can build alone.
20
33
+
21
- The people who may need to know are the ones whose code you
22
- are butchering . These people happen to be the ones who are
34
+ The people who may need to know are the ones who worked on the code
35
+ you are touching . These people happen to be the ones who are
23
36
most likely to be knowledgeable enough to help you, but
24
- they have no obligation to help you (i.e. you ask for help,
25
- don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would
37
+ they have no obligation to help you (i.e. you ask them for help,
38
+ you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would
26
39
help you find out who they are.
27
40
28
- . You get comments and suggestions for improvements. You may
29
- even get them in an "on top of your change" patch form.
30
-
31
- . Polish, refine, and re-send to the list and the people who
32
- spend their time to improve your patch. Go back to step (2).
33
-
34
- . The list forms consensus that the last round of your patch is
35
- good. Send it to the maintainer and cc the list.
36
-
37
- . A topic branch is created with the patch and is merged to `next`,
38
- and cooked further and eventually graduates to `master`.
39
-
40
- In any time between the (2)-(3) cycle, the maintainer may pick it up
41
- from the list and queue it to `seen`, in order to make it easier for
42
- people to play with it without having to pick up and apply the patch to
43
- their trees themselves.
44
-
45
- [[patch-status]]
46
- === Know the status of your patch after submission
47
-
48
- * You can use Git itself to find out when your patch is merged in
49
- master. `git pull --rebase` will automatically skip already-applied
50
- patches, and will let you know. This works only if you rebase on top
51
- of the branch in which your patch has been merged (i.e. it will not
52
- tell you if your patch is merged in `seen` if you rebase on top of
53
- master).
41
+ . You get comments and suggestions for improvements. You may even get
42
+ them in an "on top of your change" patch form. You are expected to
43
+ respond to them with "Reply-All" on the mailing list, while taking
44
+ them into account while preparing an updated set of patches.
45
+
46
+ . Polish, refine, and re-send your patches to the list and to the people
47
+ who spent their time to improve your patch. Go back to step (2).
48
+
49
+ . While the above iterations improve your patches, the maintainer may
50
+ pick the patches up from the list and queue them to the `seen`
51
+ branch, in order to make it easier for people to play with it
52
+ without having to pick up and apply the patches to their trees
53
+ themselves. Being in `seen` has no other meaning. Specifically, it
54
+ does not mean the patch was "accepted" in any way.
55
+
56
+ . When the discussion reaches a consensus that the latest iteration of
57
+ the patches are in good enough shape, the maintainer includes the
58
+ topic in the "What's cooking" report that are sent out a few times a
59
+ week to the mailing list, marked as "Will merge to 'next'." This
60
+ decision is primarily made by the maintainer with help from those
61
+ who participated in the review discussion.
62
+
63
+ . After the patches are merged to the 'next' branch, the discussion
64
+ can still continue to further improve them by adding more patches on
65
+ top, but by the time a topic gets merged to 'next', it is expected
66
+ that everybody agrees that the scope and the basic direction of the
67
+ topic are appropriate, so such an incremental updates are limited to
68
+ small corrections and polishing. After a topic cooks for some time
69
+ (like 7 calendar days) in 'next' without needing further tweaks on
70
+ top, it gets merged to the 'master' branch and wait to become part
71
+ of the next major release.
72
+
73
+ In the following sections, many techniques and conventions are listed
74
+ to help your patches get reviewed effectively in such a life cycle.
54
75
55
- * Read the Git mailing list, the maintainer regularly posts messages
56
- entitled "What's cooking in git.git" giving
57
- the status of various proposed changes.
58
76
59
77
[[choose-starting-point]]
60
78
=== Choose a starting point.
@@ -241,8 +259,9 @@ reasons:
241
259
which case, they can explain why they extend your code to cover
242
260
files, too).
243
261
244
- The goal of your log message is to convey the _why_ behind your
245
- change to help future developers.
262
+ The goal of your log message is to convey the _why_ behind your change
263
+ to help future developers. The reviewers will also make sure that
264
+ your proposed log message will serve this purpose well.
246
265
247
266
The first line of the commit message should be a short description (50
248
267
characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]),
0 commit comments