| 1 | Checklist (and a short version for the impatient): |
| 2 | |
| 3 | Commits: |
| 4 | |
| 5 | - Make commits of logical units. |
| 6 | - Check for unnecessary whitespace with "git diff --check" |
| 7 | before committing. |
| 8 | - Do not check in commented out code or unneeded files. |
| 9 | - Provide a meaningful commit message. |
| 10 | - The first line of the commit message should be a short |
| 11 | description and should skip the full stop. |
| 12 | - If you want your work included in StGit, add a |
| 13 | "Signed-off-by: Your Name <you@example.com>" line to the |
| 14 | commit message (or just use the option "-s" when |
| 15 | committing) to confirm that you agree to the Developer's |
| 16 | Certificate of Origin. |
| 17 | - Make sure that you have tests for the bug you are fixing. |
| 18 | - Make sure that the test suite passes after your commit. |
| 19 | |
| 20 | Patch: |
| 21 | |
| 22 | - Preferably use "stg mail" to send patches. The first time, |
| 23 | it's a good idea to try to mail the patches to yourself to |
| 24 | see that everything works. |
| 25 | - Do not PGP sign your patch. |
| 26 | - Do not attach your patch, but read in the mail. |
| 27 | body, unless you cannot teach your mailer to |
| 28 | leave the formatting of the patch alone. |
| 29 | - Be careful doing cut & paste into your mailer, not to |
| 30 | corrupt whitespaces. |
| 31 | - Provide additional information (which is unsuitable for the |
| 32 | commit message) between the "---" and the diffstat. (The -E |
| 33 | option to stg mail lets you edit the message before you send |
| 34 | it out.) |
| 35 | - If you change, add, or remove a command line option or |
| 36 | make some other user interface change, the associated |
| 37 | documentation should be updated as well. |
| 38 | - If your name is not writable in ASCII, make sure that |
| 39 | you send off a message in the correct encoding. |
| 40 | - Send the patch to the list (git@vger.kernel.org) and the |
| 41 | maintainer (catalin.marinas@gmail.com) if (and only if) the |
| 42 | patch is ready for inclusion. |
| 43 | |
| 44 | |
| 45 | Long version: |
| 46 | |
| 47 | |
| 48 | 1. Make separate commits for logically separate changes. |
| 49 | |
| 50 | Unless your patch is really trivial, you should not be sending out |
| 51 | a patch that was generated between your working tree and your |
| 52 | commit head. Instead, always make a commit with complete commit |
| 53 | message and generate a series of patches from your repository. It |
| 54 | is a good discipline. |
| 55 | |
| 56 | Describe the technical detail of the change(s). |
| 57 | |
| 58 | If your description starts to get too long, that's a sign that you |
| 59 | probably need to split up your commit to finer grained pieces. |
| 60 | |
| 61 | Oh, another thing. I am picky about whitespaces. Please run git |
| 62 | diff --check on your changes before you commit. |
| 63 | |
| 64 | |
| 65 | 2. Generate your patch using Git tools out of your commits. |
| 66 | |
| 67 | Git based diff tools (Git, Cogito, and StGit included) generate |
| 68 | unidiff which is the preferred format. |
| 69 | |
| 70 | You do not have to be afraid to use -M option to "git diff" and |
| 71 | friends, if your patch involves file renames. The receiving end can |
| 72 | handle them just fine. |
| 73 | |
| 74 | Please make sure your patch does not include any extra files which |
| 75 | do not belong in a patch submission. Make sure to review your patch |
| 76 | after generating it, to ensure accuracy. Before sending out, please |
| 77 | make sure it cleanly applies to the "master" branch head. If you |
| 78 | are preparing a work based on some other branch, that is fine, but |
| 79 | please mark it as such. |
| 80 | |
| 81 | |
| 82 | 3. Sending your patches. |
| 83 | |
| 84 | StGit patches should be sent to the Git mailing list |
| 85 | (git@vger.kernel.org), and preferably CCed to the StGit maintainer |
| 86 | (catalin.marinas@gmail.com). The recipients need to be able to read |
| 87 | and comment on the changes you are submitting. It is important for |
| 88 | a developer to be able to "quote" your changes, using standard |
| 89 | e-mail tools, so that they may comment on specific portions of your |
| 90 | code. For this reason, all patches should be submitted "inline". |
| 91 | WARNING: Be wary of your MUAs word-wrap corrupting your patch. Do |
| 92 | not cut-n-paste your patch; you can lose tabs that way if you are |
| 93 | not careful. |
| 94 | |
| 95 | It is a common convention to prefix your subject line with [StGit |
| 96 | PATCH]. This lets people easily distinguish patches to StGit from |
| 97 | other e-mail discussions and patches meant for Git itself. Use of |
| 98 | additional markers after PATCH and the closing bracket to mark the |
| 99 | nature of the patch is also encouraged. E.g. [PATCH/RFC] is often |
| 100 | used when the patch is not ready to be applied but it is for |
| 101 | discussion, [PATCH v2], [PATCH v3] etc. are often seen when you are |
| 102 | sending an update to what you have previously sent. |
| 103 | |
| 104 | "stg mail" command follows the best current practice to format the |
| 105 | body of an e-mail message. At the beginning of the patch should |
| 106 | come your commit message, ending with the Signed-off-by: lines, and |
| 107 | a line that consists of three dashes, followed by the diffstat |
| 108 | information and the patch itself. If you are forwarding a patch |
| 109 | from somebody else, optionally, at the beginning of the e-mail |
| 110 | message just before the commit message starts, you can put a |
| 111 | "From:" line to name that person. |
| 112 | |
| 113 | You often want to add additional explanation about the patch, other |
| 114 | than the commit message itself. Place such "cover letter" material |
| 115 | between the three dash lines and the diffstat. If you have comments |
| 116 | about a whole series of patches, you can include them in a separate |
| 117 | cover mail message (the -e option to stg mail). |
| 118 | |
| 119 | Do not attach the patch as a MIME attachment, compressed or not. Do |
| 120 | not let your e-mail client send quoted-printable. Do not let your |
| 121 | e-mail client send format=flowed which would destroy whitespaces in |
| 122 | your patches. Many popular e-mail applications will not always |
| 123 | transmit a MIME attachment as plain text, making it impossible to |
| 124 | comment on your code. A MIME attachment also takes a bit more time |
| 125 | to process. This does not decrease the likelihood of your |
| 126 | MIME-attached change being accepted, but it makes it more likely |
| 127 | that it will be postponed. |
| 128 | |
| 129 | Exception: If your mailer is mangling patches then someone may ask |
| 130 | you to re-send them using MIME, that is OK. |
| 131 | |
| 132 | Do not PGP sign your patch, at least for now. Most likely, your |
| 133 | maintainer or other people on the list would not have your PGP key |
| 134 | and would not bother obtaining it anyway. Your patch is not judged |
| 135 | by who you are; a good patch from an unknown origin has a far |
| 136 | better chance of being accepted than a patch from a known, |
| 137 | respected origin that is done poorly or does incorrect things. |
| 138 | |
| 139 | |
| 140 | 4. Sign your work |
| 141 | |
| 142 | To improve tracking of who did what, we've borrowed the "sign-off" |
| 143 | procedure from the Git and Linux kernel projects on patches that |
| 144 | are being emailed around. Although StGit is a lot smaller project |
| 145 | it is a good discipline to follow it. |
| 146 | |
| 147 | The sign-off is a simple line at the end of the explanation for the |
| 148 | patch, which certifies that you wrote it or otherwise have the |
| 149 | right to pass it on as a open-source patch. The rules are pretty |
| 150 | simple: if you can certify the below: |
| 151 | |
| 152 | Developer's Certificate of Origin 1.1 |
| 153 | |
| 154 | By making a contribution to this project, I certify that: |
| 155 | |
| 156 | (a) The contribution was created in whole or in part by me and |
| 157 | I have the right to submit it under the open source |
| 158 | license indicated in the file; or |
| 159 | |
| 160 | (b) The contribution is based upon previous work that, to the |
| 161 | best of my knowledge, is covered under an appropriate open |
| 162 | source license and I have the right under that license to |
| 163 | submit that work with modifications, whether created in |
| 164 | whole or in part by me, under the same open source license |
| 165 | (unless I am permitted to submit under a different |
| 166 | license), as indicated in the file; or |
| 167 | |
| 168 | (c) The contribution was provided directly to me by some other |
| 169 | person who certified (a), (b) or (c) and I have not |
| 170 | modified it. |
| 171 | |
| 172 | (d) I understand and agree that this project and the |
| 173 | contribution are public and that a record of the |
| 174 | contribution (including all personal information I submit |
| 175 | with it, including my sign-off) is maintained indefinitely |
| 176 | and may be redistributed consistent with this project or |
| 177 | the open source license(s) involved. |
| 178 | |
| 179 | then you just add a line saying |
| 180 | |
| 181 | Signed-off-by: Random J Developer <random@developer.example.org> |
| 182 | |
| 183 | This line can be automatically added by StGit by any command that |
| 184 | accepts the --sign option. |
| 185 | |
| 186 | Notice that you can place your own Signed-off-by: line when |
| 187 | forwarding somebody else's patch with the above rules for D-C-O. |
| 188 | Indeed you are encouraged to do so. Do not forget to place an |
| 189 | in-body "From: " line at the beginning to properly attribute the |
| 190 | change to its true author (see (2) above). |
| 191 | |
| 192 | Also notice that a real name is used in the Signed-off-by: line. |
| 193 | Please don't hide your real name. |
| 194 | |
| 195 | Some people also put extra tags at the end. |
| 196 | |
| 197 | "Acked-by:" says that the patch was reviewed by a person who is |
| 198 | more familiar with the issues and the area the patch attempts to |
| 199 | modify. "Tested-by:" says the patch was tested by the person and |
| 200 | found to have the desired effect. |
| 201 | |
| 202 | |
| 203 | ------------------------------------------------ |
| 204 | MUA specific hints |
| 205 | |
| 206 | Some of patches I receive or pick up from the list share common |
| 207 | patterns of breakage. Please make sure your MUA is set up |
| 208 | properly not to corrupt whitespaces. Here are two common ones |
| 209 | I have seen: |
| 210 | |
| 211 | * Empty context lines that do not have _any_ whitespace. |
| 212 | |
| 213 | * Non empty context lines that have one extra whitespace at the |
| 214 | beginning. |
| 215 | |
| 216 | One test you could do yourself if your MUA is set up correctly is: |
| 217 | |
| 218 | * Send the patch to yourself, exactly the way you would, except |
| 219 | To: and Cc: lines, which would not contain the list and |
| 220 | maintainer address. |
| 221 | |
| 222 | * Save that patch to a file in UNIX mailbox format. Call it say |
| 223 | a.patch. |
| 224 | |
| 225 | * Try to apply to the tip of the "master" branch from the |
| 226 | public repository: |
| 227 | |
| 228 | $ git fetch http://homepage.ntlworld.com/cmarinas/stgit.git master:test-apply |
| 229 | $ git checkout test-apply |
| 230 | $ git reset --hard |
| 231 | $ stg init |
| 232 | $ stg import -M a.patch |
| 233 | |
| 234 | If it does not apply correctly, there can be various reasons. |
| 235 | |
| 236 | * Your patch itself does not apply cleanly. That is _bad_ but |
| 237 | does not have much to do with your MUA. Please rebase the |
| 238 | patch appropriately. |
| 239 | |
| 240 | * Your MUA corrupted your patch; "stg import" would complain that |
| 241 | the patch does not apply. |
| 242 | |
| 243 | * Check the imported patch with e.g. "stg show". If it isn't exactly |
| 244 | what you would want to see in the commit log message, it is very |
| 245 | likely that the maintainer would end up hand editing the log |
| 246 | message when he applies your patch. Things like "Hi, this is my |
| 247 | first patch.\n", if you really want to put in the patch e-mail, |
| 248 | should come after the three-dash line that signals the end of the |
| 249 | commit message. |
| 250 | |
| 251 | |
| 252 | Pine |
| 253 | ---- |
| 254 | |
| 255 | (Johannes Schindelin) |
| 256 | |
| 257 | I don't know how many people still use pine, but for those poor |
| 258 | souls it may be good to mention that the quell-flowed-text is |
| 259 | needed for recent versions. |
| 260 | |
| 261 | ... the "no-strip-whitespace-before-send" option, too. AFAIK it |
| 262 | was introduced in 4.60. |
| 263 | |
| 264 | (Linus Torvalds) |
| 265 | |
| 266 | And 4.58 needs at least this. |
| 267 | |
| 268 | --- |
| 269 | diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1) |
| 270 | Author: Linus Torvalds <torvalds@g5.osdl.org> |
| 271 | Date: Mon Aug 15 17:23:51 2005 -0700 |
| 272 | |
| 273 | Fix pine whitespace-corruption bug |
| 274 | |
| 275 | There's no excuse for unconditionally removing whitespace from |
| 276 | the pico buffers on close. |
| 277 | |
| 278 | diff --git a/pico/pico.c b/pico/pico.c |
| 279 | --- a/pico/pico.c |
| 280 | +++ b/pico/pico.c |
| 281 | @@ -219,7 +219,9 @@ PICO *pm; |
| 282 | switch(pico_all_done){ /* prepare for/handle final events */ |
| 283 | case COMP_EXIT : /* already confirmed */ |
| 284 | packheader(); |
| 285 | +#if 0 |
| 286 | stripwhitespace(); |
| 287 | +#endif |
| 288 | c |= COMP_EXIT; |
| 289 | break; |
| 290 | |
| 291 | |
| 292 | (Daniel Barkalow) |
| 293 | |
| 294 | > A patch to SubmittingPatches, MUA specific help section for |
| 295 | > users of Pine 4.63 would be very much appreciated. |
| 296 | |
| 297 | Ah, it looks like a recent version changed the default behavior to do the |
| 298 | right thing, and inverted the sense of the configuration option. (Either |
| 299 | that or Gentoo did it.) So you need to set the |
| 300 | "no-strip-whitespace-before-send" option, unless the option you have is |
| 301 | "strip-whitespace-before-send", in which case you should avoid checking |
| 302 | it. |
| 303 | |
| 304 | |
| 305 | Thunderbird |
| 306 | ----------- |
| 307 | |
| 308 | (A Large Angry SCM) |
| 309 | |
| 310 | Here are some hints on how to successfully submit patches inline using |
| 311 | Thunderbird. |
| 312 | |
| 313 | This recipe appears to work with the current [*1*] Thunderbird from Suse. |
| 314 | |
| 315 | The following Thunderbird extensions are needed: |
| 316 | AboutConfig 0.5 |
| 317 | http://aboutconfig.mozdev.org/ |
| 318 | External Editor 0.7.2 |
| 319 | http://globs.org/articles.php?lng=en&pg=8 |
| 320 | |
| 321 | 1) Prepare the patch as a text file using your method of choice. |
| 322 | |
| 323 | 2) Before opening a compose window, use Edit->Account Settings to |
| 324 | uncheck the "Compose messages in HTML format" setting in the |
| 325 | "Composition & Addressing" panel of the account to be used to send the |
| 326 | patch. [*2*] |
| 327 | |
| 328 | 3) In the main Thunderbird window, _before_ you open the compose window |
| 329 | for the patch, use Tools->about:config to set the following to the |
| 330 | indicated values: |
| 331 | mailnews.send_plaintext_flowed => false |
| 332 | mailnews.wraplength => 0 |
| 333 | |
| 334 | 4) Open a compose window and click the external editor icon. |
| 335 | |
| 336 | 5) In the external editor window, read in the patch file and exit the |
| 337 | editor normally. |
| 338 | |
| 339 | 6) Back in the compose window: Add whatever other text you wish to the |
| 340 | message, complete the addressing and subject fields, and press send. |
| 341 | |
| 342 | 7) Optionally, undo the about:config/account settings changes made in |
| 343 | steps 2 & 3. |
| 344 | |
| 345 | |
| 346 | [Footnotes] |
| 347 | *1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse |
| 348 | 9.3 professional updates. |
| 349 | |
| 350 | *2* It may be possible to do this with about:config and the following |
| 351 | settings but I haven't tried, yet. |
| 352 | mail.html_compose => false |
| 353 | mail.identity.default.compose_html => false |
| 354 | mail.identity.id?.compose_html => false |
| 355 | |
| 356 | (Lukas Sandström) |
| 357 | |
| 358 | There is a script in contrib/thunderbird-patch-inline which can help |
| 359 | you include patches with Thunderbird in an easy way. To use it, do the |
| 360 | steps above and then use the script as the external editor. |
| 361 | |
| 362 | Gnus |
| 363 | ---- |
| 364 | |
| 365 | '|' in the *Summary* buffer can be used to pipe the current |
| 366 | message to an external program, and this is a handy way to drive |
| 367 | "git am". However, if the message is MIME encoded, what is |
| 368 | piped into the program is the representation you see in your |
| 369 | *Article* buffer after unwrapping MIME. This is often not what |
| 370 | you would want for two reasons. It tends to screw up non ASCII |
| 371 | characters (most notably in people's names), and also |
| 372 | whitespaces (fatal in patches). Running 'C-u g' to display the |
| 373 | message in raw form before using '|' to run the pipe can work |
| 374 | this problem around. |
| 375 | |
| 376 | |
| 377 | KMail |
| 378 | ----- |
| 379 | |
| 380 | This should help you to submit patches inline using KMail. |
| 381 | |
| 382 | 1) Prepare the patch as a text file. |
| 383 | |
| 384 | 2) Click on New Mail. |
| 385 | |
| 386 | 3) Go under "Options" in the Composer window and be sure that |
| 387 | "Word wrap" is not set. |
| 388 | |
| 389 | 4) Use Message -> Insert file... and insert the patch. |
| 390 | |
| 391 | 5) Back in the compose window: add whatever other text you wish to the |
| 392 | message, complete the addressing and subject fields, and press send. |
| 393 | |
| 394 | |
| 395 | Gmail |
| 396 | ----- |
| 397 | |
| 398 | Submitting properly formatted patches via Gmail is simple now that |
| 399 | IMAP support is available. First, edit your ~/.gitconfig to specify your |
| 400 | account settings: |
| 401 | |
| 402 | [imap] |
| 403 | folder = "[Gmail]/Drafts" |
| 404 | host = imaps://imap.gmail.com |
| 405 | user = user@gmail.com |
| 406 | pass = p4ssw0rd |
| 407 | port = 993 |
| 408 | sslverify = false |
| 409 | |
| 410 | Next, ensure that your Gmail settings are correct. In "Settings" the |
| 411 | "Use Unicode (UTF-8) encoding for outgoing messages" should be checked. |
| 412 | |
| 413 | Once your commits are ready to send to the mailing list, run the following |
| 414 | command to send the patch emails to your Gmail Drafts folder. |
| 415 | |
| 416 | $ git format-patch -M --stdout origin/master | git imap-send |
| 417 | |
| 418 | Go to your Gmail account, open the Drafts folder, find the patch email, fill |
| 419 | in the To: and CC: fields and send away! |