| I started reading over the SubmittingPatches document for Linux |
| kernel, primarily because I wanted to have a document similar to |
| it for the core GIT to make sure people understand what they are |
| doing when they write "Signed-off-by" line. |
| |
| But the patch submission requirements are a lot more relaxed |
| here, because the core GIT is thousand times smaller ;-). So |
| here is only the relevant bits. |
| |
| |
| (1) Make separate commits for logically separate changes. |
| |
| Unless your patch is really trivial, you should not be sending |
| out a patch that was generated between your working tree and |
| your commit head. Instead, always make a commit with complete |
| commit message and generate a series of patches from your |
| repository. It is a good discipline. |
| |
| Describe the technical detail of the change(s). |
| |
| If your description starts to get long, that's a sign that you |
| probably need to split up your commit to finer grained pieces. |
| |
| |
| (2) Generate your patch using git/cogito out of your commits. |
| |
| git diff tools generate unidiff which is the preferred format. |
| You do not have to be afraid to use -M option to "git diff" or |
| "git format-patch", if your patch involves file renames. The |
| receiving end can handle them just fine. |
| |
| Please make sure your patch does not include any extra files |
| which do not belong in a patch submission. Make sure to review |
| your patch after generating it, to ensure accuracy. Before |
| sending out, please make sure it cleanly applies to the "master" |
| branch head. |
| |
| |
| (3) Sending your patches. |
| |
| People on the git mailing list needs to be able to read and |
| comment on the changes you are submitting. It is important for |
| a developer to be able to "quote" your changes, using standard |
| e-mail tools, so that they may comment on specific portions of |
| your code. For this reason, all patches should be submitting |
| e-mail "inline". WARNING: Be wary of your MUAs word-wrap |
| corrupting your patch. Do not cut-n-paste your patch. |
| |
| It is common convention to prefix your subject line with |
| [PATCH]. This lets people easily distinguish patches from other |
| e-mail discussions. |
| |
| "git format-patch" command follows the best current practice to |
| format the body of an e-mail message. At the beginning of the |
| patch should come your commit message, ending with the |
| Signed-off-by: lines, and a line that consists of three dashes, |
| followed by the diffstat information and the patch itself. If |
| you are forwarding a patch from somebody else, optionally, at |
| the beginning of the e-mail message just before the commit |
| message starts, you can put a "From: " line to name that person. |
| |
| You often want to add additional explanation about the patch, |
| other than the commit message itself. Place such "cover letter" |
| material between the three dash lines and the diffstat. |
| |
| Do not attach the patch as a MIME attachment, compressed or not. |
| Do not let your e-mail client send quoted-printable. Many |
| popular e-mail applications will not always transmit a MIME |
| attachment as plain text, making it impossible to comment on |
| your code. A MIME attachment also takes a bit more time to |
| process. This does not decrease the likelihood of your |
| MIME-attached change being accepted, but it makes it more likely |
| that it will be postponed. |
| |
| Exception: If your mailer is mangling patches then someone may ask |
| you to re-send them using MIME, that is OK. |
| |
| Do not PGP sign your patch, at least for now. Most likely, your |
| maintainer or other people on the list would not have your PGP |
| key and would not bother obtaining it anyway. Your patch is not |
| judged by who you are; a good patch from an unknown origin has a |
| far better chance of being accepted than a patch from a known, |
| respected origin that is done poorly or does incorrect things. |
| |
| If you really really really really want to do a PGP signed |
| patch, format it as "multipart/signed", not a text/plain message |
| that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is |
| not a text/plain, it's something else. |
| |
| Note that your maintainer does not necessarily read everything |
| on the git mailing list. If your patch is for discussion first, |
| send it "To:" the mailing list, and optionally "cc:" him. If it |
| is trivially correct or after the list reached a consensus, send |
| it "To:" the maintainer and optionally "cc:" the list. |
| |
| |
| (6) Sign your work |
| |
| To improve tracking of who did what, we've borrowed the |
| "sign-off" procedure from the Linux kernel project on patches |
| that are being emailed around. Although core GIT is a lot |
| smaller project it is a good discipline to follow it. |
| |
| The sign-off is a simple line at the end of the explanation for |
| the patch, which certifies that you wrote it or otherwise have |
| the right to pass it on as a open-source patch. The rules are |
| pretty simple: if you can certify the below: |
| |
| Developer's Certificate of Origin 1.1 |
| |
| By making a contribution to this project, I certify that: |
| |
| (a) The contribution was created in whole or in part by me and I |
| have the right to submit it under the open source license |
| indicated in the file; or |
| |
| (b) The contribution is based upon previous work that, to the best |
| of my knowledge, is covered under an appropriate open source |
| license and I have the right under that license to submit that |
| work with modifications, whether created in whole or in part |
| by me, under the same open source license (unless I am |
| permitted to submit under a different license), as indicated |
| in the file; or |
| |
| (c) The contribution was provided directly to me by some other |
| person who certified (a), (b) or (c) and I have not modified |
| it. |
| |
| (d) I understand and agree that this project and the contribution |
| are public and that a record of the contribution (including all |
| personal information I submit with it, including my sign-off) is |
| maintained indefinitely and may be redistributed consistent with |
| this project or the open source license(s) involved. |
| |
| then you just add a line saying |
| |
| Signed-off-by: Random J Developer <random@developer.example.org> |
| |
| Some people also put extra tags at the end. They'll just be ignored for |
| now, but you can do this to mark internal company procedures or just |
| point out some special detail about the sign-off. |
| |
| |
| ------------------------------------------------ |
| MUA specific hints |
| |
| Some of patches I receive or pick up from the list share common |
| patterns of breakage. Please make sure your MUA is set up |
| properly not to corrupt whitespaces. Here are two common ones |
| I have seen: |
| |
| * Empty context lines that do not have _any_ whitespace. |
| |
| * Non empty context lines that have one extra whitespace at the |
| beginning. |
| |
| One test you could do yourself if your MUA is set up correctly is: |
| |
| * Send the patch to yourself, exactly the way you would, except |
| To: and Cc: lines, which would not contain the list and |
| maintainer address. |
| |
| * Save that patch to a file in UNIX mailbox format. Call it say |
| a.patch. |
| |
| * Try to apply to the tip of the "master" branch from the |
| git.git public repository: |
| |
| $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply |
| $ git checkout test-apply |
| $ git reset --hard |
| $ git applymbox a.patch |
| |
| If it does not apply correctly, there can be various reasons. |
| |
| * Your patch itself does not apply cleanly. That is _bad_ but |
| does not have much to do with your MUA. Please rebase the |
| patch appropriately. |
| |
| * Your MUA corrupted your patch; applymbox would complain that |
| the patch does not apply. Look at .dotest/ subdirectory and |
| see what 'patch' file contains and check for the common |
| corruption patterns mentioned above. |
| |
| * While you are at it, check what are in 'info' and |
| 'final-commit' files as well. If what is in 'final-commit' is |
| not exactly what you would want to see in the commit log |
| message, it is very likely that your maintainer would end up |
| hand editing the log message when he applies your patch. |
| Things like "Hi, this is my first patch.\n", if you really |
| want to put in the patch e-mail, should come after the |
| three-dash line that signals the end of the commit message. |
| |
| |
| Pine |
| ---- |
| |
| (Johannes Schindelin) |
| |
| I don't know how many people still use pine, but for those poor |
| souls it may be good to mention that the quell-flowed-text is |
| needed for recent versions. |
| |
| ... the "no-strip-whitespace-before-send" option, too. AFAIK it |
| was introduced in 4.60. |
| |
| (Linus Torvalds) |
| |
| And 4.58 needs at least this. |
| |
| --- |
| diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) |
| Author: Linus Torvalds <torvalds@g5.osdl.org> |
| Date: Mon Aug 15 17:23:51 2005 -0700 |
| |
| Fix pine whitespace-corruption bug |
| |
| There's no excuse for unconditionally removing whitespace from |
| the pico buffers on close. |
| |
| diff --git a/pico/pico.c b/pico/pico.c |
| --- a/pico/pico.c |
| +++ b/pico/pico.c |
| @@ -219,7 +219,9 @@ PICO *pm; |
| switch(pico_all_done){ /* prepare for/handle final events */ |
| case COMP_EXIT : /* already confirmed */ |
| packheader(); |
| +#if 0 |
| stripwhitespace(); |
| +#endif |
| c |= COMP_EXIT; |
| break; |
| |
| |
| (Daniel Barkalow) |
| |
| > A patch to SubmittingPatches, MUA specific help section for |
| > users of Pine 4.63 would be very much appreciated. |
| |
| Ah, it looks like a recent version changed the default behavior to do the |
| right thing, and inverted the sense of the configuration option. (Either |
| that or Gentoo did it.) So you need to set the |
| "no-strip-whitespace-before-send" option, unless the option you have is |
| "strip-whitespace-before-send", in which case you should avoid checking |
| it. |
| |
| |
| Thunderbird |
| ----------- |
| |
| (A Large Angry SCM) |
| |
| Here are some hints on how to successfully submit patches inline using |
| Thunderbird. |
| |
| This recipe appears to work with the current [*1*] Thunderbird from Suse. |
| |
| The following Thunderbird extensions are needed: |
| AboutConfig 0.5 |
| http://aboutconfig.mozdev.org/ |
| External Editor 0.5.4 |
| http://extensionroom.mozdev.org/more-info/exteditor |
| |
| 1) Prepare the patch as a text file using your method of choice. |
| |
| 2) Before opening a compose window, use Edit->Account Settings to |
| uncheck the "Compose messages in HTML format" setting in the |
| "Composition & Addressing" panel of the account to be used to send the |
| patch. [*2*] |
| |
| 3) In the main Thunderbird window, _before_ you open the compose window |
| for the patch, use Tools->about:config to set the following to the |
| indicated values: |
| mailnews.send_plaintext_flowed => false |
| mailnews.wraplength => 0 |
| |
| 4) Open a compose window and click the external editor icon. |
| |
| 5) In the external editor window, read in the patch file and exit the |
| editor normally. |
| |
| 6) Back in the compose window: Add whatever other text you wish to the |
| message, complete the addressing and subject fields, and press send. |
| |
| 7) Optionally, undo the about:config/account settings changes made in |
| steps 2 & 3. |
| |
| |
| [Footnotes] |
| *1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse |
| 9.3 professional updates. |
| |
| *2* It may be possible to do this with about:config and the following |
| settings but I haven't tried, yet. |
| mail.html_compose => false |
| mail.identity.default.compose_html => false |
| mail.identity.id?.compose_html => false |
| |