| blob | 6121e902ae206c95fb4503918ec91b452977442d |
1 I started reading over the SubmittingPatches document for Linux
2 kernel, primarily because I wanted to have a document similar to
3 it for the core GIT to make sure people understand what they are
4 doing when they write "Signed-off-by" line.
6 But the patch submission requirements are a lot more relaxed
7 here, because the core GIT is thousand times smaller ;-). So
8 here is only the relevant bits.
11 (1) Make separate commits for logically separate changes.
13 Unless your patch is really trivial, you should not be sending
14 out a patch that was generated between your working tree and
15 your commit head. Instead, always make a commit with complete
16 commit message and generate a series of patches from your
17 repository. It is a good discipline.
19 Describe the technical detail of the change(s).
21 If your description starts to get long, that's a sign that you
22 probably need to split up your commit to finer grained pieces.
25 (2) Generate your patch using git/cogito out of your commits.
27 git diff tools generate unidiff which is the preferred format.
28 You do not have to be afraid to use -M option to "git diff" or
29 "git format-patch", if your patch involves file renames. The
30 receiving end can handle them just fine.
32 Please make sure your patch does not include any extra files
33 which do not belong in a patch submission. Make sure to review
34 your patch after generating it, to ensure accuracy. Before
35 sending out, please make sure it cleanly applies to the "master"
36 branch head.
39 (3) Sending your patches.
41 People on the git mailing list needs to be able to read and
42 comment on the changes you are submitting. It is important for
43 a developer to be able to "quote" your changes, using standard
44 e-mail tools, so that they may comment on specific portions of
45 your code. For this reason, all patches should be submitting
46 e-mail "inline". WARNING: Be wary of your MUAs word-wrap
47 corrupting your patch. Do not cut-n-paste your patch.
49 It is common convention to prefix your subject line with
50 [PATCH]. This lets people easily distinguish patches from other
51 e-mail discussions.
53 "git format-patch" command follows the best current practice to
54 format the body of an e-mail message. At the beginning of the
55 patch should come your commit message, ending with the
56 Signed-off-by: lines, and a line that consists of three dashes,
57 followed by the diffstat information and the patch itself. If
58 you are forwarding a patch from somebody else, optionally, at
59 the beginning of the e-mail message just before the commit
60 message starts, you can put a "From: " line to name that person.
62 You often want to add additional explanation about the patch,
63 other than the commit message itself. Place such "cover letter"
64 material between the three dash lines and the diffstat.
66 Do not attach the patch as a MIME attachment, compressed or not.
67 Do not let your e-mail client send quoted-printable. Many
68 popular e-mail applications will not always transmit a MIME
69 attachment as plain text, making it impossible to comment on
70 your code. A MIME attachment also takes a bit more time to
71 process. This does not decrease the likelihood of your
72 MIME-attached change being accepted, but it makes it more likely
73 that it will be postponed.
75 Exception: If your mailer is mangling patches then someone may ask
76 you to re-send them using MIME.
78 Note that your maintainer does not subscribe to the git mailing
79 list (he reads it via mail-to-news gateway). If your patch is
80 for discussion first, send it "To:" the mailing list, and
81 optoinally "cc:" him. If it is trivially correct or after list
82 discussion reached consensus, send it "To:" the maintainer and
83 optionally "cc:" the list.
86 (6) Sign your work
88 To improve tracking of who did what, we've borrowed the
89 "sign-off" procedure from the Linux kernel project on patches
90 that are being emailed around. Although core GIT is a lot
91 smaller project it is a good discipline to follow it.
93 The sign-off is a simple line at the end of the explanation for
94 the patch, which certifies that you wrote it or otherwise have
95 the right to pass it on as a open-source patch. The rules are
96 pretty simple: if you can certify the below:
98 Developer's Certificate of Origin 1.1
100 By making a contribution to this project, I certify that:
102 (a) The contribution was created in whole or in part by me and I
103 have the right to submit it under the open source license
104 indicated in the file; or
106 (b) The contribution is based upon previous work that, to the best
107 of my knowledge, is covered under an appropriate open source
108 license and I have the right under that license to submit that
109 work with modifications, whether created in whole or in part
110 by me, under the same open source license (unless I am
111 permitted to submit under a different license), as indicated
112 in the file; or
114 (c) The contribution was provided directly to me by some other
115 person who certified (a), (b) or (c) and I have not modified
116 it.
118 (d) I understand and agree that this project and the contribution
119 are public and that a record of the contribution (including all
120 personal information I submit with it, including my sign-off) is
121 maintained indefinitely and may be redistributed consistent with
122 this project or the open source license(s) involved.
124 then you just add a line saying
126 Signed-off-by: Random J Developer <random@developer.example.org>
128 Some people also put extra tags at the end. They'll just be ignored for
129 now, but you can do this to mark internal company procedures or just
130 point out some special detail about the sign-off.