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