| 1 |
Checklist |
| 2 |
|
| 3 |
(and a short version for the impatient): |
| 4 |
|
| 5 |
Commits: |
| 6 |
|
| 7 |
* make commits of logical units |
| 8 |
* check for unnecessary whitespace with "git diff --check" before committing |
| 9 |
* do not check in commented out code or unneeded files |
| 10 |
* the first line of the commit message should be a short description and |
| 11 |
should skip the full stop |
| 12 |
* the body should provide a meaningful commit message, which: |
| 13 |
* uses the imperative, present tense: "change", not "changed" or "changes". |
| 14 |
* includes motivation for the change, and contrasts its implementation with |
| 15 |
previous behaviour |
| 16 |
* if you want your work included in the main repository, add a "Signed-off-by: |
| 17 |
Your Name <[email protected]>" line to the commit message (or just use the |
| 18 |
option "-s" when committing) to confirm that you agree to the Developer's |
| 19 |
Certificate of Origin |
| 20 |
* make sure that you have tests for the bug you are fixing |
| 21 |
* make sure that the test suite passes after your commit. This distribution |
| 22 |
is built with Dist::Zilla ensure that running `dzil test` passes. You are |
| 23 |
responsible for ensuring that generated, hand written and author tests pass. |
| 24 |
|
| 25 |
Patch: |
| 26 |
|
| 27 |
* if you change, add, or remove any features or make some other user |
| 28 |
interface change, the associated documentation should be updated as well. |
| 29 |
* if your name is not writable in ASCII, make sure that you send the |
| 30 |
patch in the correct encoding. |
| 31 |
|
| 32 |
Long version: |
| 33 |
|
| 34 |
I started reading over the SubmittingPatches document for git, |
| 35 |
primarily because I wanted to have a document similar to it for |
| 36 |
my projects to make sure people understand what they are doing |
| 37 |
when they write "Signed-off-by" line. |
| 38 |
|
| 39 |
But the patch submission requirements are a lot more relaxed |
| 40 |
here on the technical/contents front, because my projects are |
| 41 |
thousand times smaller ;-). So here is only the relevant bits. |
| 42 |
|
| 43 |
|
| 44 |
(0) Decide what to base your work on. |
| 45 |
|
| 46 |
In general, always base your work on the oldest branch that your |
| 47 |
change is relevant to. |
| 48 |
|
| 49 |
* A bugfix should be based on 'maint' in general. If the bug is not |
| 50 |
present in 'maint', base it on 'master'. For a bug that's not yet |
| 51 |
in 'master', find the topic that introduces the regression, and |
| 52 |
base your work on the tip of the topic. If a 'maint' branch is not present |
| 53 |
base it on master. |
| 54 |
|
| 55 |
* A new feature should be based on 'master' in general. If the new |
| 56 |
feature depends on a topic that is in 'pu', but not in 'master', base your |
| 57 |
work on the tip of that topic. |
| 58 |
|
| 59 |
* Corrections and enhancements to a topic not yet in 'master' should be |
| 60 |
based on the tip of that topic. If the topic has not been merged to 'next', |
| 61 |
it's alright to add a note to squash minor corrections into the series. |
| 62 |
|
| 63 |
* In the exceptional case that a new feature depends on several topics |
| 64 |
not in 'master', start working on 'next' or 'pu' privately and send out |
| 65 |
patches for discussion. Before the final merge, you may have to wait until |
| 66 |
some of the dependent topics graduate to 'master', and rebase your work. |
| 67 |
|
| 68 |
To find the tip of a topic branch, run "git log --first-parent |
| 69 |
master..pu" and look for the merge commit. The second parent of this |
| 70 |
commit is the tip of the topic branch. |
| 71 |
|
| 72 |
|
| 73 |
(1) Make separate commits for logically separate changes. |
| 74 |
|
| 75 |
Unless your patch is really trivial, you should not be sending |
| 76 |
out a patch that was generated between your working tree and |
| 77 |
your commit head. Instead, always make a commit with complete |
| 78 |
commit message and generate a series of patches from your |
| 79 |
repository. It is a good discipline. |
| 80 |
|
| 81 |
Describe the technical detail of the change(s). |
| 82 |
|
| 83 |
If your description starts to get too long, that's a sign that you |
| 84 |
probably need to split up your commit to finer grained pieces. |
| 85 |
That being said, patches which plainly describe the things that |
| 86 |
help reviewers check the patch, and future maintainers understand |
| 87 |
the code, are the most beautiful patches. Descriptions that summarise |
| 88 |
the point in the subject well, and describe the motivation for the |
| 89 |
change, the approach taken by the change, and if relevant how this |
| 90 |
differs substantially from the prior version, can be found on Usenet |
| 91 |
archives back into the late 80's. Consider it like good Netiquette, |
| 92 |
but for code. |
| 93 |
|
| 94 |
Oh, another thing. I am picky about whitespaces. Make sure your |
| 95 |
changes do not trigger errors with the sample pre-commit hook shipped |
| 96 |
in templates/hooks--pre-commit. To help ensure this does not happen, |
| 97 |
run git diff --check on your changes before you commit. |
| 98 |
|
| 99 |
|
| 100 |
(2) Generate your patch using git tools out of your commits. |
| 101 |
|
| 102 |
git based diff tools (git, Cogito, and StGIT included) generate |
| 103 |
unidiff which is the preferred format. |
| 104 |
|
| 105 |
You do not have to be afraid to use -M option to "git diff" or |
| 106 |
"git format-patch", if your patch involves file renames. The |
| 107 |
receiving end can handle them just fine. |
| 108 |
|
| 109 |
Please make sure your patch does not include any extra files |
| 110 |
which do not belong in a patch submission. Make sure to review |
| 111 |
your patch after generating it, to ensure accuracy. Before |
| 112 |
sending out, please make sure it cleanly applies to the "master" |
| 113 |
branch head. If you are preparing a work based on "next" branch, |
| 114 |
that is fine, but please mark it as such. |
| 115 |
|
| 116 |
(4) Sign your work |
| 117 |
|
| 118 |
To improve tracking of who did what, we've borrowed the |
| 119 |
"sign-off" procedure from the Linux kernel project on patches |
| 120 |
that are being emailed around. Although this project is a lot |
| 121 |
smaller it is a good discipline to follow it. |
| 122 |
|
| 123 |
The sign-off is a simple line at the end of the explanation for |
| 124 |
the patch, which certifies that you wrote it or otherwise have |
| 125 |
the right to pass it on as a open-source patch. The rules are |
| 126 |
pretty simple: if you can certify the below: |
| 127 |
|
| 128 |
Developer's Certificate of Origin 1.1 |
| 129 |
|
| 130 |
By making a contribution to this project, I certify that: |
| 131 |
|
| 132 |
(a) The contribution was created in whole or in part by me and I |
| 133 |
have the right to submit it under the open source license |
| 134 |
indicated in the file; or |
| 135 |
|
| 136 |
(b) The contribution is based upon previous work that, to the best |
| 137 |
of my knowledge, is covered under an appropriate open source |
| 138 |
license and I have the right under that license to submit that |
| 139 |
work with modifications, whether created in whole or in part |
| 140 |
by me, under the same open source license (unless I am |
| 141 |
permitted to submit under a different license), as indicated |
| 142 |
in the file; or |
| 143 |
|
| 144 |
(c) The contribution was provided directly to me by some other |
| 145 |
person who certified (a), (b) or (c) and I have not modified |
| 146 |
it. |
| 147 |
|
| 148 |
(d) I understand and agree that this project and the contribution |
| 149 |
are public and that a record of the contribution (including all |
| 150 |
personal information I submit with it, including my sign-off) is |
| 151 |
maintained indefinitely and may be redistributed consistent with |
| 152 |
this project or the open source license(s) involved. |
| 153 |
|
| 154 |
then you just add a line saying |
| 155 |
|
| 156 |
Signed-off-by: Random J Developer <[email protected]> |
| 157 |
|
| 158 |
This line can be automatically added by git if you run the git-commit |
| 159 |
command with the -s option. |
| 160 |
|
| 161 |
Notice that you can place your own Signed-off-by: line when |
| 162 |
forwarding somebody else's patch with the above rules for |
| 163 |
D-C-O. Indeed you are encouraged to do so. |
| 164 |
|
| 165 |
Also notice that a real name is used in the Signed-off-by: line. Please |
| 166 |
don't hide your real name. |
| 167 |
|
| 168 |
Some people also put extra tags at the end. |
| 169 |
|
| 170 |
"Acked-by:" says that the patch was reviewed by the person who |
| 171 |
is more familiar with the issues and the area the patch attempts |
| 172 |
to modify. "Tested-by:" says the patch was tested by the person |
| 173 |
and found to have the desired effect. |
| 174 |
|
| 175 |
|
| 176 |
An ideal patch flow |
| 177 |
|
| 178 |
Here is an ideal patch flow for this project the current maintainer |
| 179 |
suggests to the contributors: |
| 180 |
|
| 181 |
0. You come up with an itch. You code it up. |
| 182 |
1. Send it to the bug tracker and cc people who may need to know about |
| 183 |
the change. |
| 184 |
|
| 185 |
The people who may need to know are the ones whose |
| 186 |
code you are butchering. These people happen to be the ones who are most |
| 187 |
likely to be knowledgeable enough to help you, but they have no obligation to |
| 188 |
help you (i.e. you ask for help, don't demand). "git log -p -- |
| 189 |
$area_you_are_modifying" would help you find out who they are. |
| 190 |
|
| 191 |
2. You get comments and suggestions for improvements. You may even |
| 192 |
get them in a "on top of your change" patch form. |
| 193 |
|
| 194 |
3. Polish, refine, and re-send to the the people who spend their |
| 195 |
time to improve your patch. Go back to step (2). |
| 196 |
|
| 197 |
4. A topic branch is created with the patch and is merged to 'next', |
| 198 |
and cooked further and eventually graduates to 'master'. |
| 199 |
|
| 200 |
In any time between the (2)-(3) cycle, the maintainer may pick it up |
| 201 |
from the list and queue it to 'pu', in order to make it easier for |
| 202 |
people play with it without having to pick up and apply the patch to |
| 203 |
their trees themselves. |
| 204 |
|
| 205 |
|
| 206 |
Know the status of your patch after submission |
| 207 |
|
| 208 |
* You can use Git itself to find out when your patch is merged in |
| 209 |
master. 'git pull --rebase' will automatically skip already-applied |
| 210 |
patches, and will let you know. This works only if you rebase on top |
| 211 |
of the branch in which your patch has been merged (i.e. it will not |
| 212 |
tell you if your patch is merged in pu if you rebase on top of |
| 213 |
master). |