| 1 |
Submitting Patches |
| 2 |
================== |
| 3 |
|
| 4 |
== Guidelines |
| 5 |
|
| 6 |
Here are some guidelines for contributing back to this |
| 7 |
project. There is also a link:MyFirstContribution.html[step-by-step tutorial] |
| 8 |
available which covers many of these same guidelines. |
| 9 |
|
| 10 |
[[patch-flow]] |
| 11 |
=== A typical life cycle of a patch series |
| 12 |
|
| 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. |
| 16 |
|
| 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. |
| 33 |
+ |
| 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 |
| 36 |
most likely to be knowledgeable enough to help you, but |
| 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 |
| 39 |
help you find out who they are. |
| 40 |
|
| 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. |
| 75 |
|
| 76 |
|
| 77 |
[[choose-starting-point]] |
| 78 |
=== Choose a starting point. |
| 79 |
|
| 80 |
As a preliminary step, you must first choose a starting point for your |
| 81 |
work. Typically this means choosing a branch, although technically |
| 82 |
speaking it is actually a particular commit (typically the HEAD, or tip, |
| 83 |
of the branch). |
| 84 |
|
| 85 |
There are several important branches to be aware of. Namely, there are |
| 86 |
four integration branches as discussed in linkgit:gitworkflows[7]: |
| 87 |
|
| 88 |
* maint |
| 89 |
* master |
| 90 |
* next |
| 91 |
* seen |
| 92 |
|
| 93 |
The branches lower on the list are typically descendants of the ones |
| 94 |
that come before it. For example, `maint` is an "older" branch than |
| 95 |
`master` because `master` usually has patches (commits) on top of |
| 96 |
`maint`. |
| 97 |
|
| 98 |
There are also "topic" branches, which contain work from other |
| 99 |
contributors. Topic branches are created by the Git maintainer (in |
| 100 |
their fork) to organize the current set of incoming contributions on |
| 101 |
the mailing list, and are itemized in the regular "What's cooking in |
| 102 |
git.git" announcements. To find the tip of a topic branch, run `git log |
| 103 |
--first-parent master..seen` and look for the merge commit. The second |
| 104 |
parent of this commit is the tip of the topic branch. |
| 105 |
|
| 106 |
There is one guiding principle for choosing the right starting point: in |
| 107 |
general, always base your work on the oldest integration branch that |
| 108 |
your change is relevant to (see "Merge upwards" in |
| 109 |
linkgit:gitworkflows[7]). What this principle means is that for the |
| 110 |
vast majority of cases, the starting point for new work should be the |
| 111 |
latest HEAD commit of `maint` or `master` based on the following cases: |
| 112 |
|
| 113 |
* If you are fixing bugs in the released version, use `maint` as the |
| 114 |
starting point (which may mean you have to fix things without using |
| 115 |
new API features on the cutting edge that recently appeared in |
| 116 |
`master` but were not available in the released version). |
| 117 |
|
| 118 |
* Otherwise (such as if you are adding new features) use `master`. |
| 119 |
|
| 120 |
|
| 121 |
NOTE: In exceptional cases, a bug that was introduced in an old |
| 122 |
version may have to be fixed for users of releases that are much older |
| 123 |
than the recent releases. `git describe --contains X` may describe |
| 124 |
`X` as `v2.30.0-rc2-gXXXXXX` for the commit `X` that introduced the |
| 125 |
bug, and the bug may be so high-impact that we may need to issue a new |
| 126 |
maintenance release for Git 2.30.x series, when "Git 2.41.0" is the |
| 127 |
current release. In such a case, you may want to use the tip of the |
| 128 |
maintenance branch for the 2.30.x series, which may be available in the |
| 129 |
`maint-2.30` branch in https://github.com/gitster/git[the maintainer's |
| 130 |
"broken out" repo]. |
| 131 |
|
| 132 |
This also means that `next` or `seen` are inappropriate starting points |
| 133 |
for your work, if you want your work to have a realistic chance of |
| 134 |
graduating to `master`. They are simply not designed to be used as a |
| 135 |
base for new work; they are only there to make sure that topics in |
| 136 |
flight work well together. This is why both `next` and `seen` are |
| 137 |
frequently re-integrated with incoming patches on the mailing list and |
| 138 |
force-pushed to replace previous versions of themselves. A topic that is |
| 139 |
literally built on top of `next` cannot be merged to `master` without |
| 140 |
dragging in all the other topics in `next`, some of which may not be |
| 141 |
ready. |
| 142 |
|
| 143 |
For example, if you are making tree-wide changes, while somebody else is |
| 144 |
also making their own tree-wide changes, your work may have severe |
| 145 |
overlap with the other person's work. This situation may tempt you to |
| 146 |
use `next` as your starting point (because it would have the other |
| 147 |
person's work included in it), but doing so would mean you'll not only |
| 148 |
depend on the other person's work, but all the other random things from |
| 149 |
other contributors that are already integrated into `next`. And as soon |
| 150 |
as `next` is updated with a new version, all of your work will need to |
| 151 |
be rebased anyway in order for them to be cleanly applied by the |
| 152 |
maintainer. |
| 153 |
|
| 154 |
Under truly exceptional circumstances where you absolutely must depend |
| 155 |
on a select few topic branches that are already in `next` but not in |
| 156 |
`master`, you may want to create your own custom base-branch by forking |
| 157 |
`master` and merging the required topic branches into it. You could then |
| 158 |
work on top of this base-branch. But keep in mind that this base-branch |
| 159 |
would only be known privately to you. So when you are ready to send |
| 160 |
your patches to the list, be sure to communicate how you created it in |
| 161 |
your cover letter. This critical piece of information would allow |
| 162 |
others to recreate your base-branch on their end in order for them to |
| 163 |
try out your work. |
| 164 |
|
| 165 |
Finally, note that some parts of the system have dedicated maintainers |
| 166 |
with their own separate source code repositories (see the section |
| 167 |
"Subsystems" below). |
| 168 |
|
| 169 |
[[separate-commits]] |
| 170 |
=== Make separate commits for logically separate changes. |
| 171 |
|
| 172 |
Unless your patch is really trivial, you should not be sending |
| 173 |
out a patch that was generated between your working tree and |
| 174 |
your commit head. Instead, always make a commit with complete |
| 175 |
commit message and generate a series of patches from your |
| 176 |
repository. It is a good discipline. |
| 177 |
|
| 178 |
Give an explanation for the change(s) that is detailed enough so |
| 179 |
that people can judge if it is good thing to do, without reading |
| 180 |
the actual patch text to determine how well the code does what |
| 181 |
the explanation promises to do. |
| 182 |
|
| 183 |
If your description starts to get too long, that's a sign that you |
| 184 |
probably need to split up your commit to finer grained pieces. |
| 185 |
That being said, patches which plainly describe the things that |
| 186 |
help reviewers check the patch, and future maintainers understand |
| 187 |
the code, are the most beautiful patches. Descriptions that summarize |
| 188 |
the point in the subject well, and describe the motivation for the |
| 189 |
change, the approach taken by the change, and if relevant how this |
| 190 |
differs substantially from the prior version, are all good things |
| 191 |
to have. |
| 192 |
|
| 193 |
Make sure that you have tests for the bug you are fixing. See |
| 194 |
`t/README` for guidance. |
| 195 |
|
| 196 |
[[tests]] |
| 197 |
When adding a new feature, make sure that you have new tests to show |
| 198 |
the feature triggers the new behavior when it should, and to show the |
| 199 |
feature does not trigger when it shouldn't. After any code change, |
| 200 |
make sure that the entire test suite passes. When fixing a bug, make |
| 201 |
sure you have new tests that break if somebody else breaks what you |
| 202 |
fixed by accident to avoid regression. Also, try merging your work to |
| 203 |
'next' and 'seen' and make sure the tests still pass; topics by others |
| 204 |
that are still in flight may have unexpected interactions with what |
| 205 |
you are trying to do in your topic. |
| 206 |
|
| 207 |
Pushing to a fork of https://github.com/git/git will use their CI |
| 208 |
integration to test your changes on Linux, Mac and Windows. See the |
| 209 |
<<GHCI,GitHub CI>> section for details. |
| 210 |
|
| 211 |
Do not forget to update the documentation to describe the updated |
| 212 |
behavior and make sure that the resulting documentation set formats |
| 213 |
well (try the Documentation/doc-diff script). |
| 214 |
|
| 215 |
We currently have a liberal mixture of US and UK English norms for |
| 216 |
spelling and grammar, which is somewhat unfortunate. A huge patch that |
| 217 |
touches the files all over the place only to correct the inconsistency |
| 218 |
is not welcome, though. Potential clashes with other changes that can |
| 219 |
result from such a patch are not worth it. We prefer to gradually |
| 220 |
reconcile the inconsistencies in favor of US English, with small and |
| 221 |
easily digestible patches, as a side effect of doing some other real |
| 222 |
work in the vicinity (e.g. rewriting a paragraph for clarity, while |
| 223 |
turning en_UK spelling to en_US). Obvious typographical fixes are much |
| 224 |
more welcomed ("teh -> "the"), preferably submitted as independent |
| 225 |
patches separate from other documentation changes. |
| 226 |
|
| 227 |
[[whitespace-check]] |
| 228 |
Oh, another thing. We are picky about whitespaces. Make sure your |
| 229 |
changes do not trigger errors with the sample pre-commit hook shipped |
| 230 |
in `templates/hooks--pre-commit`. To help ensure this does not happen, |
| 231 |
run `git diff --check` on your changes before you commit. |
| 232 |
|
| 233 |
[[describe-changes]] |
| 234 |
=== Describe your changes well. |
| 235 |
|
| 236 |
The log message that explains your changes is just as important as the |
| 237 |
changes themselves. Your code may be clearly written with in-code |
| 238 |
comment to sufficiently explain how it works with the surrounding |
| 239 |
code, but those who need to fix or enhance your code in the future |
| 240 |
will need to know _why_ your code does what it does, for a few |
| 241 |
reasons: |
| 242 |
|
| 243 |
. Your code may be doing something differently from what you wanted it |
| 244 |
to do. Writing down what you actually wanted to achieve will help |
| 245 |
them fix your code and make it do what it should have been doing |
| 246 |
(also, you often discover your own bugs yourself, while writing the |
| 247 |
log message to summarize the thought behind it). |
| 248 |
|
| 249 |
. Your code may be doing things that were only necessary for your |
| 250 |
immediate needs (e.g. "do X to directories" without implementing or |
| 251 |
even designing what is to be done on files). Writing down why you |
| 252 |
excluded what the code does not do will help guide future developers. |
| 253 |
Writing down "we do X to directories, because directories have |
| 254 |
characteristic Y" would help them infer "oh, files also have the same |
| 255 |
characteristic Y, so perhaps doing X to them would also make sense?". |
| 256 |
Saying "we don't do the same X to files, because ..." will help them |
| 257 |
decide if the reasoning is sound (in which case they do not waste |
| 258 |
time extending your code to cover files), or reason differently (in |
| 259 |
which case, they can explain why they extend your code to cover |
| 260 |
files, too). |
| 261 |
|
| 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. |
| 265 |
|
| 266 |
The first line of the commit message should be a short description (50 |
| 267 |
characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]), |
| 268 |
and should skip the full stop. It is also conventional in most cases to |
| 269 |
prefix the first line with "area: " where the area is a filename or |
| 270 |
identifier for the general area of the code being modified, e.g. |
| 271 |
|
| 272 |
* doc: clarify distinction between sign-off and pgp-signing |
| 273 |
* githooks.txt: improve the intro section |
| 274 |
|
| 275 |
If in doubt which identifier to use, run `git log --no-merges` on the |
| 276 |
files you are modifying to see the current conventions. |
| 277 |
|
| 278 |
[[summary-section]] |
| 279 |
The title sentence after the "area:" prefix omits the full stop at the |
| 280 |
end, and its first word is not capitalized (the omission |
| 281 |
of capitalization applies only to the word after the "area:" |
| 282 |
prefix of the title) unless there is a reason to |
| 283 |
capitalize it other than because it is the first word in the sentence. |
| 284 |
E.g. "doc: clarify...", not "doc: Clarify...", or "githooks.txt: |
| 285 |
improve...", not "githooks.txt: Improve...". But "refs: HEAD is also |
| 286 |
treated as a ref" is correct, as we spell `HEAD` in all caps even when |
| 287 |
it appears in the middle of a sentence. |
| 288 |
|
| 289 |
[[meaningful-message]] |
| 290 |
The body should provide a meaningful commit message, which: |
| 291 |
|
| 292 |
. explains the problem the change tries to solve, i.e. what is wrong |
| 293 |
with the current code without the change. |
| 294 |
|
| 295 |
. justifies the way the change solves the problem, i.e. why the |
| 296 |
result with the change is better. |
| 297 |
|
| 298 |
. alternate solutions considered but discarded, if any. |
| 299 |
|
| 300 |
[[present-tense]] |
| 301 |
The problem statement that describes the status quo is written in the |
| 302 |
present tense. Write "The code does X when it is given input Y", |
| 303 |
instead of "The code used to do Y when given input X". You do not |
| 304 |
have to say "Currently"---the status quo in the problem statement is |
| 305 |
about the code _without_ your change, by project convention. |
| 306 |
|
| 307 |
[[imperative-mood]] |
| 308 |
Describe your changes in imperative mood, e.g. "make xyzzy do frotz" |
| 309 |
instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy |
| 310 |
to do frotz", as if you are giving orders to the codebase to change |
| 311 |
its behavior. Try to make sure your explanation can be understood |
| 312 |
without external resources. Instead of giving a URL to a mailing list |
| 313 |
archive, summarize the relevant points of the discussion. |
| 314 |
|
| 315 |
[[commit-reference]] |
| 316 |
|
| 317 |
There are a few reasons why you may want to refer to another commit in |
| 318 |
the "more stable" part of the history (i.e. on branches like `maint`, |
| 319 |
`master`, and `next`): |
| 320 |
|
| 321 |
. A commit that introduced the root cause of a bug you are fixing. |
| 322 |
|
| 323 |
. A commit that introduced a feature that you are enhancing. |
| 324 |
|
| 325 |
. A commit that conflicts with your work when you made a trial merge |
| 326 |
of your work into `next` and `seen` for testing. |
| 327 |
|
| 328 |
When you reference a commit on a more stable branch (like `master`, |
| 329 |
`maint` and `next`), use the format "abbreviated hash (subject, |
| 330 |
date)", like this: |
| 331 |
|
| 332 |
.... |
| 333 |
Commit f86a374 (pack-bitmap.c: fix a memleak, 2015-03-30) |
| 334 |
noticed that ... |
| 335 |
.... |
| 336 |
|
| 337 |
The "Copy commit reference" command of gitk can be used to obtain this |
| 338 |
format (with the subject enclosed in a pair of double-quotes), or this |
| 339 |
invocation of `git show`: |
| 340 |
|
| 341 |
.... |
| 342 |
git show -s --pretty=reference <commit> |
| 343 |
.... |
| 344 |
|
| 345 |
or, on an older version of Git without support for --pretty=reference: |
| 346 |
|
| 347 |
.... |
| 348 |
git show -s --date=short --pretty='format:%h (%s, %ad)' <commit> |
| 349 |
.... |
| 350 |
|
| 351 |
[[sign-off]] |
| 352 |
=== Certify your work by adding your `Signed-off-by` trailer |
| 353 |
|
| 354 |
To improve tracking of who did what, we ask you to certify that you |
| 355 |
wrote the patch or have the right to pass it on under the same license |
| 356 |
as ours, by "signing off" your patch. Without sign-off, we cannot |
| 357 |
accept your patches. |
| 358 |
|
| 359 |
If (and only if) you certify the below D-C-O: |
| 360 |
|
| 361 |
[[dco]] |
| 362 |
.Developer's Certificate of Origin 1.1 |
| 363 |
____ |
| 364 |
By making a contribution to this project, I certify that: |
| 365 |
|
| 366 |
a. The contribution was created in whole or in part by me and I |
| 367 |
have the right to submit it under the open source license |
| 368 |
indicated in the file; or |
| 369 |
|
| 370 |
b. The contribution is based upon previous work that, to the best |
| 371 |
of my knowledge, is covered under an appropriate open source |
| 372 |
license and I have the right under that license to submit that |
| 373 |
work with modifications, whether created in whole or in part |
| 374 |
by me, under the same open source license (unless I am |
| 375 |
permitted to submit under a different license), as indicated |
| 376 |
in the file; or |
| 377 |
|
| 378 |
c. The contribution was provided directly to me by some other |
| 379 |
person who certified (a), (b) or (c) and I have not modified |
| 380 |
it. |
| 381 |
|
| 382 |
d. I understand and agree that this project and the contribution |
| 383 |
are public and that a record of the contribution (including all |
| 384 |
personal information I submit with it, including my sign-off) is |
| 385 |
maintained indefinitely and may be redistributed consistent with |
| 386 |
this project or the open source license(s) involved. |
| 387 |
____ |
| 388 |
|
| 389 |
you add a "Signed-off-by" trailer to your commit, that looks like |
| 390 |
this: |
| 391 |
|
| 392 |
.... |
| 393 |
Signed-off-by: Random J Developer <[email protected]> |
| 394 |
.... |
| 395 |
|
| 396 |
This line can be added by Git if you run the git-commit command with |
| 397 |
the -s option. |
| 398 |
|
| 399 |
Notice that you can place your own `Signed-off-by` trailer when |
| 400 |
forwarding somebody else's patch with the above rules for |
| 401 |
D-C-O. Indeed you are encouraged to do so. Do not forget to |
| 402 |
place an in-body "From: " line at the beginning to properly attribute |
| 403 |
the change to its true author (see (2) above). |
| 404 |
|
| 405 |
This procedure originally came from the Linux kernel project, so our |
| 406 |
rule is quite similar to theirs, but what exactly it means to sign-off |
| 407 |
your patch differs from project to project, so it may be different |
| 408 |
from that of the project you are accustomed to. |
| 409 |
|
| 410 |
[[real-name]] |
| 411 |
Please use a known identity in the `Signed-off-by` trailer, since we cannot |
| 412 |
accept anonymous contributions. It is common, but not required, to use some form |
| 413 |
of your real name. We realize that some contributors are not comfortable doing |
| 414 |
so or prefer to contribute under a pseudonym or preferred name and we can accept |
| 415 |
your patch either way, as long as the name and email you use are distinctive, |
| 416 |
identifying, and not misleading. |
| 417 |
|
| 418 |
The goal of this policy is to allow us to have sufficient information to contact |
| 419 |
you if questions arise about your contribution. |
| 420 |
|
| 421 |
[[commit-trailers]] |
| 422 |
If you like, you can put extra trailers at the end: |
| 423 |
|
| 424 |
. `Reported-by:` is used to credit someone who found the bug that |
| 425 |
the patch attempts to fix. |
| 426 |
. `Acked-by:` says that the person who is more familiar with the area |
| 427 |
the patch attempts to modify liked the patch. |
| 428 |
. `Reviewed-by:`, unlike the other trailers, can only be offered by the |
| 429 |
reviewers themselves when they are completely satisfied with the |
| 430 |
patch after a detailed analysis. |
| 431 |
. `Tested-by:` is used to indicate that the person applied the patch |
| 432 |
and found it to have the desired effect. |
| 433 |
. `Co-authored-by:` is used to indicate that people exchanged drafts |
| 434 |
of a patch before submitting it. |
| 435 |
. `Helped-by:` is used to credit someone who suggested ideas for |
| 436 |
changes without providing the precise changes in patch form. |
| 437 |
. `Mentored-by:` is used to credit someone with helping develop a |
| 438 |
patch as part of a mentorship program (e.g., GSoC or Outreachy). |
| 439 |
. `Suggested-by:` is used to credit someone with suggesting the idea |
| 440 |
for a patch. |
| 441 |
|
| 442 |
While you can also create your own trailer if the situation warrants it, we |
| 443 |
encourage you to instead use one of the common trailers in this project |
| 444 |
highlighted above. |
| 445 |
|
| 446 |
Only capitalize the very first letter of the trailer, i.e. favor |
| 447 |
"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By". |
| 448 |
|
| 449 |
[[git-tools]] |
| 450 |
=== Generate your patch using Git tools out of your commits. |
| 451 |
|
| 452 |
Git based diff tools generate unidiff which is the preferred format. |
| 453 |
|
| 454 |
You do not have to be afraid to use `-M` option to `git diff` or |
| 455 |
`git format-patch`, if your patch involves file renames. The |
| 456 |
receiving end can handle them just fine. |
| 457 |
|
| 458 |
[[review-patch]] |
| 459 |
Please make sure your patch does not add commented out debugging code, |
| 460 |
or include any extra files which do not relate to what your patch |
| 461 |
is trying to achieve. Make sure to review |
| 462 |
your patch after generating it, to ensure accuracy. Before |
| 463 |
sending out, please make sure it cleanly applies to the starting point you |
| 464 |
have chosen in the "Choose a starting point" section. |
| 465 |
|
| 466 |
NOTE: From the perspective of those reviewing your patch, the `master` |
| 467 |
branch is the default expected starting point. So if you have chosen a |
| 468 |
different starting point, please communicate this choice in your cover |
| 469 |
letter. |
| 470 |
|
| 471 |
|
| 472 |
[[send-patches]] |
| 473 |
=== Sending your patches. |
| 474 |
|
| 475 |
==== Choosing your reviewers |
| 476 |
|
| 477 |
:security-ml: footnoteref:[security-ml,The Git Security mailing list: [email protected]] |
| 478 |
|
| 479 |
NOTE: Patches that may be |
| 480 |
security relevant should be submitted privately to the Git Security |
| 481 |
mailing list{security-ml}, instead of the public mailing list. |
| 482 |
|
| 483 |
:contrib-scripts: footnoteref:[contrib-scripts,Scripts under `contrib/` are + |
| 484 |
not part of the core `git` binary and must be called directly. Clone the Git + |
| 485 |
codebase and run `perl contrib/contacts/git-contacts`.] |
| 486 |
|
| 487 |
Send your patch with "To:" set to the mailing list, with "cc:" listing |
| 488 |
people who are involved in the area you are touching (the `git-contacts` |
| 489 |
script in `contrib/contacts/`{contrib-scripts} can help to |
| 490 |
identify them), to solicit comments and reviews. Also, when you made |
| 491 |
trial merges of your topic to `next` and `seen`, you may have noticed |
| 492 |
work by others conflicting with your changes. There is a good possibility |
| 493 |
that these people may know the area you are touching well. |
| 494 |
|
| 495 |
If you are using `send-email`, you can feed it the output of `git-contacts` like |
| 496 |
this: |
| 497 |
|
| 498 |
.... |
| 499 |
git send-email --cc-cmd='perl contrib/contacts/git-contacts' feature/*.patch |
| 500 |
.... |
| 501 |
|
| 502 |
:current-maintainer: footnote:[The current maintainer: [email protected]] |
| 503 |
:git-ml: footnote:[The mailing list: [email protected]] |
| 504 |
|
| 505 |
After the list reached a consensus that it is a good idea to apply the |
| 506 |
patch, re-send it with "To:" set to the maintainer{current-maintainer} |
| 507 |
and "cc:" the list{git-ml} for inclusion. This is especially relevant |
| 508 |
when the maintainer did not heavily participate in the discussion and |
| 509 |
instead left the review to trusted others. |
| 510 |
|
| 511 |
Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and |
| 512 |
`Tested-by:` lines as necessary to credit people who helped your |
| 513 |
patch, and "cc:" them when sending such a final version for inclusion. |
| 514 |
|
| 515 |
==== `format-patch` and `send-email` |
| 516 |
|
| 517 |
Learn to use `format-patch` and `send-email` if possible. These commands |
| 518 |
are optimized for the workflow of sending patches, avoiding many ways |
| 519 |
your existing e-mail client (often optimized for "multipart/*" MIME |
| 520 |
type e-mails) might render your patches unusable. |
| 521 |
|
| 522 |
NOTE: Here we outline the procedure using `format-patch` and |
| 523 |
`send-email`, but you can instead use GitGitGadget to send in your |
| 524 |
patches (see link:MyFirstContribution.html[MyFirstContribution]). |
| 525 |
|
| 526 |
People on the Git mailing list need to be able to read and |
| 527 |
comment on the changes you are submitting. It is important for |
| 528 |
a developer to be able to "quote" your changes, using standard |
| 529 |
e-mail tools, so that they may comment on specific portions of |
| 530 |
your code. For this reason, each patch should be submitted |
| 531 |
"inline" in a separate message. |
| 532 |
|
| 533 |
All subsequent versions of a patch series and other related patches should be |
| 534 |
grouped into their own e-mail thread to help readers find all parts of the |
| 535 |
series. To that end, send them as replies to either an additional "cover |
| 536 |
letter" message (see below), the first patch, or the respective preceding patch. |
| 537 |
Here is a link:MyFirstContribution.html#v2-git-send-email[step-by-step guide] on |
| 538 |
how to submit updated versions of a patch series. |
| 539 |
|
| 540 |
If your log message (including your name on the |
| 541 |
`Signed-off-by` trailer) is not writable in ASCII, make sure that |
| 542 |
you send off a message in the correct encoding. |
| 543 |
|
| 544 |
WARNING: Be wary of your MUAs word-wrap |
| 545 |
corrupting your patch. Do not cut-n-paste your patch; you can |
| 546 |
lose tabs that way if you are not careful. |
| 547 |
|
| 548 |
It is a common convention to prefix your subject line with |
| 549 |
[PATCH]. This lets people easily distinguish patches from other |
| 550 |
e-mail discussions. Use of markers in addition to PATCH within |
| 551 |
the brackets to describe the nature of the patch is also |
| 552 |
encouraged. E.g. [RFC PATCH] (where RFC stands for "request for |
| 553 |
comments") is often used to indicate a patch needs further |
| 554 |
discussion before being accepted, [PATCH v2], [PATCH v3] etc. |
| 555 |
are often seen when you are sending an update to what you have |
| 556 |
previously sent. |
| 557 |
|
| 558 |
The `git format-patch` command follows the best current practice to |
| 559 |
format the body of an e-mail message. At the beginning of the |
| 560 |
patch should come your commit message, ending with the |
| 561 |
`Signed-off-by` trailers, and a line that consists of three dashes, |
| 562 |
followed by the diffstat information and the patch itself. If |
| 563 |
you are forwarding a patch from somebody else, optionally, at |
| 564 |
the beginning of the e-mail message just before the commit |
| 565 |
message starts, you can put a "From: " line to name that person. |
| 566 |
To change the default "[PATCH]" in the subject to "[<text>]", use |
| 567 |
`git format-patch --subject-prefix=<text>`. As a shortcut, you |
| 568 |
can use `--rfc` instead of `--subject-prefix="RFC PATCH"`, or |
| 569 |
`-v <n>` instead of `--subject-prefix="PATCH v<n>"`. |
| 570 |
|
| 571 |
You often want to add additional explanation about the patch, |
| 572 |
other than the commit message itself. Place such "cover letter" |
| 573 |
material between the three-dash line and the diffstat. For |
| 574 |
patches requiring multiple iterations of review and discussion, |
| 575 |
an explanation of changes between each iteration can be kept in |
| 576 |
Git-notes and inserted automatically following the three-dash |
| 577 |
line via `git format-patch --notes`. |
| 578 |
|
| 579 |
[[the-topic-summary]] |
| 580 |
*This is EXPERIMENTAL*. |
| 581 |
|
| 582 |
When sending a topic, you can propose a one-paragraph summary that |
| 583 |
should appear in the "What's cooking" report when it is picked up to |
| 584 |
explain the topic. If you choose to do so, please write a 2-5 line |
| 585 |
paragraph that will fit well in our release notes (see many bulleted |
| 586 |
entries in the Documentation/RelNotes/* files for examples), and make |
| 587 |
it the first paragraph of the cover letter. For a single-patch |
| 588 |
series, use the space between the three-dash line and the diffstat, as |
| 589 |
described earlier. |
| 590 |
|
| 591 |
[[attachment]] |
| 592 |
Do not attach the patch as a MIME attachment, compressed or not. |
| 593 |
Do not let your e-mail client send quoted-printable. Do not let |
| 594 |
your e-mail client send format=flowed which would destroy |
| 595 |
whitespaces in your patches. Many |
| 596 |
popular e-mail applications will not always transmit a MIME |
| 597 |
attachment as plain text, making it impossible to comment on |
| 598 |
your code. A MIME attachment also takes a bit more time to |
| 599 |
process. This does not decrease the likelihood of your |
| 600 |
MIME-attached change being accepted, but it makes it more likely |
| 601 |
that it will be postponed. |
| 602 |
|
| 603 |
Exception: If your mailer is mangling patches then someone may ask |
| 604 |
you to re-send them using MIME, that is OK. |
| 605 |
|
| 606 |
[[pgp-signature]] |
| 607 |
Do not PGP sign your patch. Most likely, your maintainer or other people on the |
| 608 |
list would not have your PGP key and would not bother obtaining it anyway. |
| 609 |
Your patch is not judged by who you are; a good patch from an unknown origin |
| 610 |
has a far better chance of being accepted than a patch from a known, respected |
| 611 |
origin that is done poorly or does incorrect things. |
| 612 |
|
| 613 |
If you really really really really want to do a PGP signed |
| 614 |
patch, format it as "multipart/signed", not a text/plain message |
| 615 |
that starts with `-----BEGIN PGP SIGNED MESSAGE-----`. That is |
| 616 |
not a text/plain, it's something else. |
| 617 |
|
| 618 |
=== Handling Conflicts and Iterating Patches |
| 619 |
|
| 620 |
When revising changes made to your patches, it's important to |
| 621 |
acknowledge the possibility of conflicts with other ongoing topics. To |
| 622 |
navigate these potential conflicts effectively, follow the recommended |
| 623 |
steps outlined below: |
| 624 |
|
| 625 |
. Build on a suitable base branch, see the <<choose-starting-point, section above>>, |
| 626 |
and format-patch the series. If you are doing "rebase -i" in-place to |
| 627 |
update from the previous round, this will reuse the previous base so |
| 628 |
(2) and (3) may become trivial. |
| 629 |
|
| 630 |
. Find the base of where the last round was queued |
| 631 |
+ |
| 632 |
$ mine='kn/ref-transaction-symref' |
| 633 |
$ git checkout "origin/seen^{/^Merge branch '$mine'}...master" |
| 634 |
|
| 635 |
. Apply your format-patch result. There are two cases |
| 636 |
.. Things apply cleanly and tests fine. Go to (4). |
| 637 |
.. Things apply cleanly but does not build or test fails, or things do |
| 638 |
not apply cleanly. |
| 639 |
+ |
| 640 |
In the latter case, you have textual or semantic conflicts coming from |
| 641 |
the difference between the old base and the base you used to build in |
| 642 |
(1). Identify what caused the breakages (e.g., a topic or two may have |
| 643 |
merged since the base used by (2) until the base used by (1)). |
| 644 |
+ |
| 645 |
Check out the latest 'origin/master' (which may be newer than the base |
| 646 |
used by (2)), "merge --no-ff" the topics you newly depend on in there, |
| 647 |
and use the result of the merge(s) as the base, rebuild the series and |
| 648 |
test again. Run format-patch from the last such merges to the tip of |
| 649 |
your topic. If you did |
| 650 |
+ |
| 651 |
$ git checkout origin/master |
| 652 |
$ git merge --no-ff --into-name kn/ref-transaction-symref fo/obar |
| 653 |
$ git merge --no-ff --into-name kn/ref-transaction-symref ba/zqux |
| 654 |
... rebuild the topic ... |
| 655 |
+ |
| 656 |
Then you'd just format your topic above these "preparing the ground" |
| 657 |
merges, e.g. |
| 658 |
+ |
| 659 |
$ git format-patch "HEAD^{/^Merge branch 'ba/zqux'}"..HEAD |
| 660 |
+ |
| 661 |
Do not forget to write in the cover letter you did this, including the |
| 662 |
topics you have in your base on top of 'master'. Then go to (4). |
| 663 |
|
| 664 |
. Make a trial merge of your topic into 'next' and 'seen', e.g. |
| 665 |
+ |
| 666 |
$ git checkout --detach 'origin/seen' |
| 667 |
$ git revert -m 1 <the merge of the previous iteration into seen> |
| 668 |
$ git merge kn/ref-transaction-symref |
| 669 |
+ |
| 670 |
The "revert" is needed if the previous iteration of your topic is |
| 671 |
already in 'seen' (like in this case). You could choose to rebuild |
| 672 |
master..origin/seen from scratch while excluding your previous |
| 673 |
iteration, which may emulate what happens on the maintainers end more |
| 674 |
closely. |
| 675 |
+ |
| 676 |
This trial merge may conflict. It is primarily to see what conflicts |
| 677 |
_other_ topics may have with your topic. In other words, you do not |
| 678 |
have to depend on it to make your topic work on 'master'. It may |
| 679 |
become the job of the other topic owners to resolve conflicts if your |
| 680 |
topic goes to 'next' before theirs. |
| 681 |
+ |
| 682 |
Make a note on what conflict you saw in the cover letter. You do not |
| 683 |
necessarily have to resolve them, but it would be a good opportunity to |
| 684 |
learn what others are doing in related areas. |
| 685 |
+ |
| 686 |
$ git checkout --detach 'origin/next' |
| 687 |
$ git merge kn/ref-transaction-symref |
| 688 |
+ |
| 689 |
This is to see what conflicts your topic has with other topics that are |
| 690 |
already cooking. This should not conflict if (3)-2 prepared a base on |
| 691 |
top of updated master plus dependent topics taken from 'next'. Unless |
| 692 |
the context is severe (one way to tell is try the same trial merge with |
| 693 |
your old iteration, which may conflict in a similar way), expect that it |
| 694 |
will be handled on maintainers end (if it gets unmanageable, I'll ask to |
| 695 |
rebase when I receive your patches). |
| 696 |
|
| 697 |
== Subsystems with dedicated maintainers |
| 698 |
|
| 699 |
Some parts of the system have dedicated maintainers with their own |
| 700 |
repositories. |
| 701 |
|
| 702 |
- `git-gui/` comes from the git-gui project, maintained by Johannes Sixt: |
| 703 |
|
| 704 |
https://github.com/j6t/git-gui |
| 705 |
|
| 706 |
Contibutions should go via the git mailing list. |
| 707 |
|
| 708 |
- `gitk-git/` comes from the gitk project, maintained by Johannes Sixt: |
| 709 |
|
| 710 |
https://github.com/j6t/gitk |
| 711 |
|
| 712 |
Contibutions should go via the git mailing list. |
| 713 |
|
| 714 |
- `po/` comes from the localization coordinator, Jiang Xin: |
| 715 |
|
| 716 |
https://github.com/git-l10n/git-po/ |
| 717 |
|
| 718 |
Patches to these parts should be based on their trees. |
| 719 |
|
| 720 |
- The "Git documentation translations" project, led by Jean-Noël |
| 721 |
Avila, translates our documentation pages. Their work products are |
| 722 |
maintained separately from this project, not as part of our tree: |
| 723 |
|
| 724 |
https://github.com/jnavila/git-manpages-l10n/ |
| 725 |
|
| 726 |
|
| 727 |
== GitHub CI[[GHCI]] |
| 728 |
|
| 729 |
With an account at GitHub, you can use GitHub CI to test your changes |
| 730 |
on Linux, Mac and Windows. See |
| 731 |
https://github.com/git/git/actions/workflows/main.yml for examples of |
| 732 |
recent CI runs. |
| 733 |
|
| 734 |
Follow these steps for the initial setup: |
| 735 |
|
| 736 |
. Fork https://github.com/git/git to your GitHub account. |
| 737 |
You can find detailed instructions how to fork here: |
| 738 |
https://help.github.com/articles/fork-a-repo/ |
| 739 |
|
| 740 |
After the initial setup, CI will run whenever you push new changes |
| 741 |
to your fork of Git on GitHub. You can monitor the test state of all your |
| 742 |
branches here: `https://github.com/<Your GitHub handle>/git/actions/workflows/main.yml` |
| 743 |
|
| 744 |
If a branch does not pass all test cases then it will be marked with a |
| 745 |
red +x+, instead of a green check. In that case, you can click on the |
| 746 |
failing job and navigate to "ci/run-build-and-tests.sh" and/or |
| 747 |
"ci/print-test-failures.sh". You can also download "Artifacts" which |
| 748 |
are zip archives containing tarred (or zipped) archives with test data |
| 749 |
relevant for debugging. |
| 750 |
|
| 751 |
Then fix the problem and push your fix to your GitHub fork. This will |
| 752 |
trigger a new CI build to ensure all tests pass. |
| 753 |
|
| 754 |
[[mua]] |
| 755 |
== MUA specific hints |
| 756 |
|
| 757 |
Some of the patches I receive or pick up from the list share common |
| 758 |
patterns of breakage. Please make sure your MUA is set up |
| 759 |
properly not to corrupt whitespaces. |
| 760 |
|
| 761 |
See the DISCUSSION section of linkgit:git-format-patch[1] for hints on |
| 762 |
checking your patch by mailing it to yourself and applying with |
| 763 |
linkgit:git-am[1]. |
| 764 |
|
| 765 |
While you are at it, check the resulting commit log message from |
| 766 |
a trial run of applying the patch. If what is in the resulting |
| 767 |
commit is not exactly what you would want to see, it is very |
| 768 |
likely that your maintainer would end up hand editing the log |
| 769 |
message when he applies your patch. Things like "Hi, this is my |
| 770 |
first patch.\n", if you really want to put in the patch e-mail, |
| 771 |
should come after the three-dash line that signals the end of the |
| 772 |
commit message. |
| 773 |
|
| 774 |
|
| 775 |
=== Pine |
| 776 |
|
| 777 |
(Johannes Schindelin) |
| 778 |
|
| 779 |
.... |
| 780 |
I don't know how many people still use pine, but for those poor |
| 781 |
souls it may be good to mention that the quell-flowed-text is |
| 782 |
needed for recent versions. |
| 783 |
|
| 784 |
... the "no-strip-whitespace-before-send" option, too. AFAIK it |
| 785 |
was introduced in 4.60. |
| 786 |
.... |
| 787 |
|
| 788 |
(Linus Torvalds) |
| 789 |
|
| 790 |
.... |
| 791 |
And 4.58 needs at least this. |
| 792 |
|
| 793 |
diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) |
| 794 |
Author: Linus Torvalds <[email protected]> |
| 795 |
Date: Mon Aug 15 17:23:51 2005 -0700 |
| 796 |
|
| 797 |
Fix pine whitespace-corruption bug |
| 798 |
|
| 799 |
There's no excuse for unconditionally removing whitespace from |
| 800 |
the pico buffers on close. |
| 801 |
|
| 802 |
diff --git a/pico/pico.c b/pico/pico.c |
| 803 |
--- a/pico/pico.c |
| 804 |
+++ b/pico/pico.c |
| 805 |
@@ -219,7 +219,9 @@ PICO *pm; |
| 806 |
switch(pico_all_done){ /* prepare for/handle final events */ |
| 807 |
case COMP_EXIT : /* already confirmed */ |
| 808 |
packheader(); |
| 809 |
+#if 0 |
| 810 |
stripwhitespace(); |
| 811 |
+#endif |
| 812 |
c |= COMP_EXIT; |
| 813 |
break; |
| 814 |
.... |
| 815 |
|
| 816 |
(Daniel Barkalow) |
| 817 |
|
| 818 |
.... |
| 819 |
> A patch to SubmittingPatches, MUA specific help section for |
| 820 |
> users of Pine 4.63 would be very much appreciated. |
| 821 |
|
| 822 |
Ah, it looks like a recent version changed the default behavior to do the |
| 823 |
right thing, and inverted the sense of the configuration option. (Either |
| 824 |
that or Gentoo did it.) So you need to set the |
| 825 |
"no-strip-whitespace-before-send" option, unless the option you have is |
| 826 |
"strip-whitespace-before-send", in which case you should avoid checking |
| 827 |
it. |
| 828 |
.... |
| 829 |
|
| 830 |
=== Thunderbird, KMail, GMail |
| 831 |
|
| 832 |
See the MUA-SPECIFIC HINTS section of linkgit:git-format-patch[1]. |
| 833 |
|
| 834 |
=== Gnus |
| 835 |
|
| 836 |
"|" in the `*Summary*` buffer can be used to pipe the current |
| 837 |
message to an external program, and this is a handy way to drive |
| 838 |
`git am`. However, if the message is MIME encoded, what is |
| 839 |
piped into the program is the representation you see in your |
| 840 |
`*Article*` buffer after unwrapping MIME. This is often not what |
| 841 |
you would want for two reasons. It tends to screw up non-ASCII |
| 842 |
characters (most notably in people's names), and also |
| 843 |
whitespaces (fatal in patches). Running "C-u g" to display the |
| 844 |
message in raw form before using "|" to run the pipe can work |
| 845 |
this problem around. |