{"thread":{"id":"1493","subject":"[PATCH] Add SubmittingPatches","startedAt":"2005-08-13T09:08:57Z","lastAt":"2005-08-16T15:22:11Z","messageCount":10,"participants":["Junio C Hamano","Johannes Schindelin","Linus Torvalds","Ryan Anderson","A Large Angry SCM"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"7181","messageId":"7vslxep5jq.fsf@assigned-by-dhcp.cox.net","threadId":"1493","inReplyTo":null,"subject":"[PATCH] Add SubmittingPatches","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-08-13T09:08:57Z","receivedAt":"2005-08-13T09:08:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Not that I have stricter patch submission standards than ordinary\nprojects, I wanted to have it to make sure people understand\nwhat they are doing when they add their own Signed-off-by line.\n\nSigned-off-by: Junio C Hamano <junkio@cox.net>\n---\n\n Documentation/SubmittingPatches |  130 +++++++++++++++++++++++++++++++++++++++\n 1 files changed, 130 insertions(+), 0 deletions(-)\n create mode 100644 Documentation/SubmittingPatches\n\n3de1a21da62e2ad89bfb25f742384b9af496e4e0\ndiff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches\nnew file mode 100644\n--- /dev/null\n+++ b/Documentation/SubmittingPatches\n@@ -0,0 +1,130 @@\n+I started reading over the SubmittingPatches document for Linux\n+kernel, primarily because I wanted to have a document similar to\n+it for the core GIT to make sure people understand what they are\n+doing when they write \"Signed-off-by\" line.\n+\n+But the patch submission requirements are a lot more relaxed\n+here, because the core GIT is thousand times smaller ;-).  So\n+here is only the relevant bits.\n+\n+\n+(1) Make separate commits for logically separate changes.\n+\n+Unless your patch is really trivial, you should not be sending\n+out a patch that was generated between your working tree and\n+your commit head.  Instead, always make a commit with complete\n+commit message and generate a series of patches from your\n+repository.  It is a good discipline.\n+\n+Describe the technical detail of the change(s).\n+\n+If your description starts to get long, that's a sign that you\n+probably need to split up your commit to finer grained pieces.\n+\n+\n+(2) Generate your patch using git/cogito out of your commits.\n+\n+git diff tools generate unidiff which is the preferred format.\n+You do not have to be afraid to use -M option to \"git diff\" or\n+\"git format-patch\", if your patch involves file renames.  The\n+receiving end can handle them just fine.\n+\n+Please make sure your patch does not include any extra files\n+which do not belong in a patch submission.  Make sure to review\n+your patch after generating it, to ensure accuracy.  Before\n+sending out, please make sure it cleanly applies to the \"master\"\n+branch head.\n+\n+\n+(3) Sending your patches.\n+\n+People on the git mailing list needs to be able to read and\n+comment on the changes you are submitting.  It is important for\n+a developer to be able to \"quote\" your changes, using standard\n+e-mail tools, so that they may comment on specific portions of\n+your code.  For this reason, all patches should be submitting\n+e-mail \"inline\".  WARNING: Be wary of your MUAs word-wrap\n+corrupting your patch.  Do not cut-n-paste your patch.\n+\n+It is common convention to prefix your subject line with\n+[PATCH].  This lets people easily distinguish patches from other\n+e-mail discussions.\n+\n+\"git format-patch\" command follows the best current practice to\n+format the body of an e-mail message.  At the beginning of the\n+patch should come your commit message, ending with the\n+Signed-off-by: lines, and a line that consists of three dashes,\n+followed by the diffstat information and the patch itself.  If\n+you are forwarding a patch from somebody else, optionally, at\n+the beginning of the e-mail message just before the commit\n+message starts, you can put a \"From: \" line to name that person.\n+\n+You often want to add additional explanation about the patch,\n+other than the commit message itself.  Place such \"cover letter\"\n+material between the three dash lines and the diffstat.\n+\n+Do not attach the patch as a MIME attachment, compressed or not.\n+Do not let your e-mail client send quoted-printable.  Many\n+popular e-mail applications will not always transmit a MIME\n+attachment as plain text, making it impossible to comment on\n+your code.  A MIME attachment also takes a bit more time to\n+process.  This does not decrease the likelihood of your\n+MIME-attached change being accepted, but it makes it more likely\n+that it will be postponed.\n+\n+Exception:  If your mailer is mangling patches then someone may ask\n+you to re-send them using MIME.\n+\n+Note that your maintainer does not subscribe to the git mailing\n+list (he reads it via mail-to-news gateway).  If your patch is\n+for discussion first, send it \"To:\" the mailing list, and\n+optoinally \"cc:\" him.  If it is trivially correct or after list\n+discussion reached consensus, send it \"To:\" the maintainer and\n+optionally \"cc:\" the list.\n+\n+\n+(6) Sign your work\n+\n+To improve tracking of who did what, we've borrowed the\n+\"sign-off\" procedure from the Linux kernel project on patches\n+that are being emailed around.  Although core GIT is a lot\n+smaller project it is a good discipline to follow it.\n+\n+The sign-off is a simple line at the end of the explanation for\n+the patch, which certifies that you wrote it or otherwise have\n+the right to pass it on as a open-source patch.  The rules are\n+pretty simple: if you can certify the below:\n+\n+        Developer's Certificate of Origin 1.1\n+\n+        By making a contribution to this project, I certify that:\n+\n+        (a) The contribution was created in whole or in part by me and I\n+            have the right to submit it under the open source license\n+            indicated in the file; or\n+\n+        (b) The contribution is based upon previous work that, to the best\n+            of my knowledge, is covered under an appropriate open source\n+            license and I have the right under that license to submit that\n+            work with modifications, whether created in whole or in part\n+            by me, under the same open source license (unless I am\n+            permitted to submit under a different license), as indicated\n+            in the file; or\n+\n+        (c) The contribution was provided directly to me by some other\n+            person who certified (a), (b) or (c) and I have not modified\n+            it.\n+\n+\t(d) I understand and agree that this project and the contribution\n+\t    are public and that a record of the contribution (including all\n+\t    personal information I submit with it, including my sign-off) is\n+\t    maintained indefinitely and may be redistributed consistent with\n+\t    this project or the open source license(s) involved.\n+\n+then you just add a line saying\n+\n+\tSigned-off-by: Random J Developer <random@developer.example.org>\n+\n+Some people also put extra tags at the end.  They'll just be ignored for\n+now, but you can do this to mark internal company procedures or just\n+point out some special detail about the sign-off.\n"},{"id":"7326","messageId":"Pine.LNX.4.63.0508160147560.26580@wgmdd8.biozentrum.uni-wuerzburg.de","threadId":"1493","inReplyTo":"7vslxep5jq.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Add SubmittingPatches","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2005-08-15T23:50:56Z","receivedAt":"2005-08-15T23:50:56Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Sat, 13 Aug 2005, Junio C Hamano wrote:\n\n> +Note that your maintainer does not subscribe to the git mailing\n> +list (he reads it via mail-to-news gateway).\n\nWow. I didn't even read a newsgroup in decades...\n\nBTW, I don't know how many people still use pine, but for those poor souls \nit may be good to mention that the quell-flowed-text is needed for recent \nversions.\n\nCiao,\nDscho\n"},{"id":"7332","messageId":"Pine.LNX.4.58.0508151715520.3553@g5.osdl.org","threadId":"1493","inReplyTo":"Pine.LNX.4.63.0508160147560.26580@wgmdd8.biozentrum.uni-wuerzburg.de","subject":"Re: [PATCH] Add SubmittingPatches","fromName":"Linus Torvalds","fromEmail":"torvalds@osdl.org","sentAt":"2005-08-16T00:24:56Z","receivedAt":"2005-08-16T00:24:56Z","isPatch":true,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Tue, 16 Aug 2005, Johannes Schindelin wrote:\n> \n> BTW, I don't know how many people still use pine, but for those poor souls \n> it may be good to mention that the quell-flowed-text is needed for recent \n> versions.\n\nAnd 4.58 needs at least this\n\n\t\tLinus\n\n---\ndiff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)\nAuthor: Linus Torvalds <torvalds@g5.osdl.org>\nDate:   Mon Aug 15 17:23:51 2005 -0700\n\n    Fix pine whitespace-corruption bug\n    \n    There's no excuse for unconditionally removing whitespace from\n    the pico buffers on close.\n\ndiff --git a/pico/pico.c b/pico/pico.c\n--- a/pico/pico.c\n+++ b/pico/pico.c\n@@ -219,7 +219,9 @@ PICO *pm;\n \t    switch(pico_all_done){\t/* prepare for/handle final events */\n \t      case COMP_EXIT :\t\t/* already confirmed */\n \t\tpackheader();\n+#if 0\n \t\tstripwhitespace();\n+#endif\n \t\tc |= COMP_EXIT;\n \t\tbreak;\n \n"},{"id":"7333","messageId":"7viry6sp7k.fsf@assigned-by-dhcp.cox.net","threadId":"1493","inReplyTo":"Pine.LNX.4.63.0508160147560.26580@wgmdd8.biozentrum.uni-wuerzburg.de","subject":"Re: [PATCH] Add SubmittingPatches","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-08-16T00:25:03Z","receivedAt":"2005-08-16T00:25:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n\n> BTW, I don't know how many people still use pine, but for those poor souls \n> it may be good to mention that the quell-flowed-text is needed for recent \n> versions.\n\nContributions from pine users are very much appreciated.  Among\nthe patches I either receive or pick up from the list, 15-20%\nhave WS corruption one way or another, which is starting to\nannoy me.  What annoys me more are MIME quoted printable,\nthough, but that is partly my fault.\n\nI haven't counted what percentage of those WS corrupted ones are\nfrom Pine, so please do not take the above 15-20% number to have\nanything to do with Pine.\n"},{"id":"7334","messageId":"7vbr3ysomb.fsf@assigned-by-dhcp.cox.net","threadId":"1493","inReplyTo":"Pine.LNX.4.58.0508151715520.3553@g5.osdl.org","subject":"Re: [PATCH] Add SubmittingPatches","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-08-16T00:37:48Z","receivedAt":"2005-08-16T00:37:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Linus Torvalds <torvalds@osdl.org> writes:\n\n> And 4.58 needs at least this\n\n> diff-tree 8326dd8350be64ac7fc805f6563a1d61ad10d32c (from e886a61f76edf5410573e92e38ce22974f9c40f1)\n> Author: Linus Torvalds <torvalds@g5.osdl.org>\n> Date:   Mon Aug 15 17:23:51 2005 -0700\n>\n>     Fix pine whitespace-corruption bug\n>     \n>     There's no excuse for unconditionally removing whitespace from\n>     the pico buffers on close.\n\nWow.\n\nThis is a _terrible_ one.  Isn't pico code also supposed to be a\nstandalone editor of some sort?  I wonder how anybody could\ntolerate this kind of \"dictatorship ;-)\".\n\nAt least the changelog entry seems to say that 4.60 removed this\n\"feature\".\n"},{"id":"7335","messageId":"Pine.LNX.4.63.0508160252310.26927@wgmdd8.biozentrum.uni-wuerzburg.de","threadId":"1493","inReplyTo":"Pine.LNX.4.58.0508151715520.3553@g5.osdl.org","subject":"Re: [PATCH] Add SubmittingPatches","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2005-08-16T01:03:10Z","receivedAt":"2005-08-16T01:03:10Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Mon, 15 Aug 2005, Linus Torvalds wrote:\n\n> On Tue, 16 Aug 2005, Johannes Schindelin wrote:\n> > \n> > BTW, I don't know how many people still use pine, but for those poor souls \n> > it may be good to mention that the quell-flowed-text is needed for recent \n> > versions.\n> \n> And 4.58 needs at least this\n>\n>[...]\n\nSorry, I forgot the \"no-strip-whitespace-before-send\" option, too. AFAIK \nit was introduced in 4.60 (the \"fix\" Junio was referring to).\n\nMaybe we should enhance git-applymbox to detect whitespace corruption in \nparticular, and output the User-Agent header (or if that does not \nexist, the Message-ID header; thanks, pine) on error.\n\nCiao,\nDscho\n"},{"id":"7337","messageId":"7vk6imr7x0.fsf@assigned-by-dhcp.cox.net","threadId":"1493","inReplyTo":"Pine.LNX.4.63.0508160252310.26927@wgmdd8.biozentrum.uni-wuerzburg.de","subject":"Re: [PATCH] Add SubmittingPatches","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-08-16T01:23:55Z","receivedAt":"2005-08-16T01:23:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n\n> Maybe we should enhance git-applymbox to detect whitespace corruption in \n> particular, and output the User-Agent header (or if that does not \n> exist, the Message-ID header; thanks, pine) on error.\n\nWe _could_ but I doubt it would help anybody.  The damage is\nalready done.\n"},{"id":"7338","messageId":"Pine.LNX.4.63.0508160335420.1574@wgmdd8.biozentrum.uni-wuerzburg.de","threadId":"1493","inReplyTo":"7vk6imr7x0.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Add SubmittingPatches","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2005-08-16T01:41:04Z","receivedAt":"2005-08-16T01:41:04Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Mon, 15 Aug 2005, Junio C Hamano wrote:\n\n> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n> \n> > Maybe we should enhance git-applymbox to detect whitespace corruption in \n> > particular, and output the User-Agent header (or if that does not \n> > exist, the Message-ID header; thanks, pine) on error.\n> \n\nAlternatively, SubmittingPatches could include a big fat CAVEAT, and a \nnote that the submitter might want to send a single SP to herself, save \nthe received mail and check that all is well, prior to sending the first \npatch. I mean, well, erm, it is sort of, uh, annoying, to send out a \ncorrupt patch *speaksofyourstruly*.\n\nCiao,\nDscho\n"},{"id":"7344","messageId":"20050816032811.GI7001@mythryan2.michonline.com","threadId":"1493","inReplyTo":"Pine.LNX.4.63.0508160335420.1574@wgmdd8.biozentrum.uni-wuerzburg.de","subject":"Re: [PATCH] Add SubmittingPatches","fromName":"Ryan Anderson","fromEmail":"ryan@michonline.com","sentAt":"2005-08-16T03:28:11Z","receivedAt":"2005-08-16T03:28:11Z","isPatch":true,"sender":{"key":"ryan@michonline.com","avatar":null},"body":"On Tue, Aug 16, 2005 at 03:41:04AM +0200, Johannes Schindelin wrote:\n> On Mon, 15 Aug 2005, Junio C Hamano wrote:\n> \n> > Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n> > \n> > > Maybe we should enhance git-applymbox to detect whitespace corruption in \n> > > particular, and output the User-Agent header (or if that does not \n> > > exist, the Message-ID header; thanks, pine) on error.\n> > \n> \n> Alternatively, SubmittingPatches could include a big fat CAVEAT, and a \n> note that the submitter might want to send a single SP to herself, save \n> the received mail and check that all is well, prior to sending the first \n> patch. I mean, well, erm, it is sort of, uh, annoying, to send out a \n> corrupt patch *speaksofyourstruly*.\n\nIf you have some trouble sending them out, you can use\n\tgit format-patch --mbox\nand\n\tgit send-email\n\nwhich seems to consistently do the right thing.\n\n\n-- \n\nRyan Anderson\n  sometimes Pug Majere\n"},{"id":"7362","messageId":"430204A3.2050201@gmail.com","threadId":"1493","inReplyTo":"Pine.LNX.4.63.0508160335420.1574@wgmdd8.biozentrum.uni-wuerzburg.de","subject":"Submitting patches w/ Thunderbird [was: Re: [PATCH] Add SubmittingPatches]","fromName":"A Large Angry SCM","fromEmail":"gitzilla@gmail.com","sentAt":"2005-08-16T15:22:11Z","receivedAt":"2005-08-16T15:22:11Z","isPatch":true,"sender":{"key":"gitzilla@gmail.com","avatar":"https://gravatar.com/avatar/354625c442439908ff3dd99757dee330e29e9df7847472384faf7a00add247fb?d=mp&s=160"},"body":"Johannes Schindelin wrote:\n> Hi,\n> \n> On Mon, 15 Aug 2005, Junio C Hamano wrote:\n> \n>>Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n>>\n>>>Maybe we should enhance git-applymbox to detect whitespace corruption in \n>>>particular, and output the User-Agent header (or if that does not \n>>>exist, the Message-ID header; thanks, pine) on error.\n> \n> Alternatively, SubmittingPatches could include a big fat CAVEAT, and a \n> note that the submitter might want to send a single SP to herself, save \n> the received mail and check that all is well, prior to sending the first \n> patch. I mean, well, erm, it is sort of, uh, annoying, to send out a \n> corrupt patch *speaksofyourstruly*.\n\nHere are some hints on how to successfully submit patches inline using\nThunderbird.\n\nThis recipe appears to work with the current [*1*] Thunderbird from Suse.\n\nThe following Thunderbird extensions are needed:\n\tAboutConfig 0.5\n\t\thttp://aboutconfig.mozdev.org/\n\tExternal Editor 0.5.4\n\t\thttp://extensionroom.mozdev.org/more-info/exteditor\n\n1) Prepare the patch as a text file using your method of choice.\n\n2) Before opening a compose window, use Edit->Account Settings to\nuncheck the \"Compose messages in HTML format\" setting in the\n\"Composition & Addressing\" panel of the account to be used to send the\npatch. [*2*]\n\n3) In the main Thunderbird window, _before_ you open the compose window\nfor the patch, use Tools->about:config to set the following to the\nindicated values:\n\tmailnews.send_plaintext_flowed\t=> false\n\tmailnews.wraplength\t\t=> 999\n\n4) Open a compose window and click the external editor icon.\n\n5) In the external editor window, read in the patch file and exit the\neditor normally.\n\n6) Back in the compose window: Add whatever other text you wish to the\nmessage, complete the addressing and subject fields, and press send.\n\n7) Optionally, undo the about:config/account settings changes made in\nsteps 2 & 3.\n\n\n[Footnotes]\n*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse\n9.3 professional updates.\n\n*2* It may be possible to do this with about:config and the following\nsettings but I haven't tried, yet.\n\tmail.html_compose\t\t\t=> false\n\tmail.identity.default.compose_html\t=> false\n\tmail.identity.id?.compose_html\t\t=> false\n"}]}