| Checklist (and a short version for the impatient): |
| |
| Commits: |
| |
| - Make commits of logical units. |
| - Check for unnecessary whitespace with "git diff --check" |
| before committing. |
| - Do not check in commented out code or unneeded files. |
| - Provide a meaningful commit message. |
| - The first line of the commit message should be a short |
| description and should skip the full stop. |
| - If you want your work included in StGit, add a |
| "Signed-off-by: Your Name <you@example.com>" line to the |
| commit message (or just use the option "-s" when |
| committing) to confirm that you agree to the Developer's |
| Certificate of Origin. |
| - Make sure that you have tests for the bug you are fixing. |
| - Make sure that the test suite passes after your commit. |
| |
| Patch: |
| |
| - Preferably use "stg mail" to send patches. The first time, |
| it's a good idea to try to mail the patches to yourself to |
| see that everything works. |
| - Do not PGP sign your patch. |
| - Do not attach your patch, but read in the mail. |
| body, unless you cannot teach your mailer to |
| leave the formatting of the patch alone. |
| - Be careful doing cut & paste into your mailer, not to |
| corrupt whitespaces. |
| - Provide additional information (which is unsuitable for the |
| commit message) between the "---" and the diffstat. (The -E |
| option to stg mail lets you edit the message before you send |
| it out.) |
| - If you change, add, or remove a command line option or |
| make some other user interface change, the associated |
| documentation should be updated as well. |
| - If your name is not writable in ASCII, make sure that |
| you send off a message in the correct encoding. |
| - Send the patch to the list (git@vger.kernel.org) and the |
| maintainer (catalin.marinas@gmail.com) if (and only if) the |
| patch is ready for inclusion. |
| |
| |
| Long version: |
| |
| |
| 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 too long, that's a sign that you |
| probably need to split up your commit to finer grained pieces. |
| |
| Oh, another thing. I am picky about whitespaces. Please run git |
| diff --check on your changes before you commit. |
| |
| |
| 2. Generate your patch using Git tools out of your commits. |
| |
| Git based diff tools (Git, Cogito, and StGit included) generate |
| unidiff which is the preferred format. |
| |
| You do not have to be afraid to use -M option to "git diff" and |
| friends, 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. If you |
| are preparing a work based on some other branch, that is fine, but |
| please mark it as such. |
| |
| |
| 3. Sending your patches. |
| |
| StGit patches should be sent to the Git mailing list |
| (git@vger.kernel.org), and preferably CCed to the StGit maintainer |
| (catalin.marinas@gmail.com). The recipients need 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 submitted "inline". |
| WARNING: Be wary of your MUAs word-wrap corrupting your patch. Do |
| not cut-n-paste your patch; you can lose tabs that way if you are |
| not careful. |
| |
| It is a common convention to prefix your subject line with [StGit |
| PATCH]. This lets people easily distinguish patches to StGit from |
| other e-mail discussions and patches meant for Git itself. Use of |
| additional markers after PATCH and the closing bracket to mark the |
| nature of the patch is also encouraged. E.g. [PATCH/RFC] is often |
| used when the patch is not ready to be applied but it is for |
| discussion, [PATCH v2], [PATCH v3] etc. are often seen when you are |
| sending an update to what you have previously sent. |
| |
| "stg mail" 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. If you have comments |
| about a whole series of patches, you can include them in a separate |
| cover mail message (the -e option to stg mail). |
| |
| Do not attach the patch as a MIME attachment, compressed or not. Do |
| not let your e-mail client send quoted-printable. Do not let your |
| e-mail client send format=flowed which would destroy whitespaces in |
| your patches. 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. |
| |
| |
| 4. Sign your work |
| |
| To improve tracking of who did what, we've borrowed the "sign-off" |
| procedure from the Git and Linux kernel projects on patches that |
| are being emailed around. Although StGit 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> |
| |
| This line can be automatically added by StGit by any command that |
| accepts the --sign option. |
| |
| Notice that you can place your own Signed-off-by: line when |
| forwarding somebody else's patch with the above rules for D-C-O. |
| Indeed you are encouraged to do so. Do not forget to place an |
| in-body "From: " line at the beginning to properly attribute the |
| change to its true author (see (2) above). |
| |
| Also notice that a real name is used in the Signed-off-by: line. |
| Please don't hide your real name. |
| |
| Some people also put extra tags at the end. |
| |
| "Acked-by:" says that the patch was reviewed by a person who is |
| more familiar with the issues and the area the patch attempts to |
| modify. "Tested-by:" says the patch was tested by the person and |
| found to have the desired effect. |
| |
| |
| ------------------------------------------------ |
| 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 |
| public repository: |
| |
| $ git fetch http://homepage.ntlworld.com/cmarinas/stgit.git master:test-apply |
| $ git checkout test-apply |
| $ git reset --hard |
| $ stg init |
| $ stg import -M 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; "stg import" would complain that |
| the patch does not apply. |
| |
| * Check the imported patch with e.g. "stg show". If it isn't exactly |
| what you would want to see in the commit log message, it is very |
| likely that the 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.7.2 |
| http://globs.org/articles.php?lng=en&pg=8 |
| |
| 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 |
| |
| (Lukas Sandström) |
| |
| There is a script in contrib/thunderbird-patch-inline which can help |
| you include patches with Thunderbird in an easy way. To use it, do the |
| steps above and then use the script as the external editor. |
| |
| Gnus |
| ---- |
| |
| '|' in the *Summary* buffer can be used to pipe the current |
| message to an external program, and this is a handy way to drive |
| "git am". However, if the message is MIME encoded, what is |
| piped into the program is the representation you see in your |
| *Article* buffer after unwrapping MIME. This is often not what |
| you would want for two reasons. It tends to screw up non ASCII |
| characters (most notably in people's names), and also |
| whitespaces (fatal in patches). Running 'C-u g' to display the |
| message in raw form before using '|' to run the pipe can work |
| this problem around. |
| |
| |
| KMail |
| ----- |
| |
| This should help you to submit patches inline using KMail. |
| |
| 1) Prepare the patch as a text file. |
| |
| 2) Click on New Mail. |
| |
| 3) Go under "Options" in the Composer window and be sure that |
| "Word wrap" is not set. |
| |
| 4) Use Message -> Insert file... and insert the patch. |
| |
| 5) Back in the compose window: add whatever other text you wish to the |
| message, complete the addressing and subject fields, and press send. |
| |
| |
| Gmail |
| ----- |
| |
| Submitting properly formatted patches via Gmail is simple now that |
| IMAP support is available. First, edit your ~/.gitconfig to specify your |
| account settings: |
| |
| [imap] |
| folder = "[Gmail]/Drafts" |
| host = imaps://imap.gmail.com |
| user = user@gmail.com |
| pass = p4ssw0rd |
| port = 993 |
| sslverify = false |
| |
| Next, ensure that your Gmail settings are correct. In "Settings" the |
| "Use Unicode (UTF-8) encoding for outgoing messages" should be checked. |
| |
| Once your commits are ready to send to the mailing list, run the following |
| command to send the patch emails to your Gmail Drafts folder. |
| |
| $ git format-patch -M --stdout origin/master | git imap-send |
| |
| Go to your Gmail account, open the Drafts folder, find the patch email, fill |
| in the To: and CC: fields and send away! |