[PATCH 1/2] Partition SubmittingPatches doc into two files

[PATCH 1/2] Partition SubmittingPatches doc into two files

[Roberto Tyley]

No editorial changes in this commit, the text that is transferred into the
second file is unchanged apart from minor chunk re-ordering.

The split is based on:

* Information needed for all users, whether using `git send-email` or
  submitGit (ie good commit practice, mailing list etiquette)
* Information needed just for `git send-email`/MUA users (generating the
  right kind of diff, avoid MIME & PGP, send-email & MUA specific hints)
---
 Documentation/SubmittingPatches      | 137 ---------------------------------
 Documentation/SubmittingPatchesByMUA | 142 +++++++++++++++++++++++++++++++++++
 2 files changed, 142 insertions(+), 137 deletions(-)
 create mode 100644 Documentation/SubmittingPatchesByMUA

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 98fc4cc..6dca41d 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -119,11 +119,6 @@ archive, summarize the relevant points of the discussion.
 
 (3) Generate your patch using Git tools out of your commits.
 
-Git based 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 add commented out debugging code,
 or include any extra files which do not relate to what your patch
@@ -136,11 +131,6 @@ that is fine, but please mark it as such.
 
 (4) Sending your patches.
 
-Learn to use format-patch and send-email if possible.  These commands
-are optimized for the workflow of sending patches, avoiding many ways
-your existing e-mail client that is optimized for "multipart/*" mime
-type e-mails to corrupt and render your patches unusable.
-
 People on the Git mailing list 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
@@ -148,18 +138,8 @@ e-mail tools, so that they may comment on specific portions of
 your code.  For this reason, each patch should be submitted
 "inline" in a separate message.
 
-Multiple related patches should be grouped into their own e-mail
-thread to help readers find all parts of the series.  To that end,
-send them as replies to either an additional "cover letter" message
-(see below), the first patch, or the respective preceding patch.
 
-If your log message (including your name on the
-Signed-off-by line) is not writable in ASCII, make sure that
-you send off a message in the correct encoding.
 
-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
 [PATCH].  This lets people easily distinguish patches from other
@@ -187,31 +167,6 @@ an explanation of changes between each iteration can be kept in
 Git-notes and inserted automatically following the three-dash
 line via `git format-patch --notes`.
 
-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.
-
-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.
 
 Send your patch with "To:" set to the mailing list, with "cc:" listing
 people who are involved in the area you are touching (the output from
@@ -370,95 +325,3 @@ Know the status of your patch after submission
   entitled "What's cooking in git.git" and "What's in git.git" giving
   the status of various proposed changes.
 
-------------------------------------------------
-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.
-
-See the DISCUSSION section of git-format-patch(1) for hints on
-checking your patch by mailing it to yourself and applying with
-git-am(1).
-
-While you are at it, check the resulting commit log message from
-a trial run of applying the patch.  If what is in the resulting
-commit is not exactly what you would want to see, 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, KMail, GMail
--------------------------
-
-See the MUA-SPECIFIC HINTS section of git-format-patch(1).
-
-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.
diff --git a/Documentation/SubmittingPatchesByMUA b/Documentation/SubmittingPatchesByMUA
new file mode 100644
index 0000000..b3ffbc0
--- /dev/null
+++ b/Documentation/SubmittingPatchesByMUA
@@ -0,0 +1,142 @@
+Learn to use format-patch and send-email if possible.  These commands
+are optimized for the workflow of sending patches, avoiding many ways
+your existing e-mail client that is optimized for "multipart/*" mime
+type e-mails to corrupt and render your patches unusable.
+
+Git based 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.
+
+Multiple related patches should be grouped into their own e-mail
+thread to help readers find all parts of the series.  To that end,
+send them as replies to either an additional "cover letter" message
+(see below), the first patch, or the respective preceding patch.
+
+If your log message (including your name on the
+Signed-off-by line) is not writable in ASCII, make sure that
+you send off a message in the correct encoding.
+
+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.
+
+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.
+
+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.
+
+------------------------------------------------
+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.
+
+See the DISCUSSION section of git-format-patch(1) for hints on
+checking your patch by mailing it to yourself and applying with
+git-am(1).
+
+While you are at it, check the resulting commit log message from
+a trial run of applying the patch.  If what is in the resulting
+commit is not exactly what you would want to see, 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, KMail, GMail
+-------------------------
+
+See the MUA-SPECIFIC HINTS section of git-format-patch(1).
+
+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.

--
https://github.com/git/git/pull/223

[PATCH 2/2] Add submitGit patch-submission information

[Roberto Tyley]

Most of the guidance on how to use submitGit will stay with the tool
itself, so the edits here are mostly to make the choice clear to users.

Because generation of patches is quite different for MUA-users and
submitGit users, I've merged section 3 and 4 together:

section 3 - 'Generate your patch using Git tools out of your commits.'
+
section 4 - 'Sending your patches.'
=
new section 3 - 'Generate and send your patch to the Git mailing list'

I've edited the text of old section 3 to make it more concise (using
'make sure' for emphasis just once before presenting the requirements
list).
---
 Documentation/SubmittingPatches | 44 +++++++++++++++++++++++++++--------------
 1 file changed, 29 insertions(+), 15 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 6dca41d..9735236 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -117,29 +117,43 @@ without external resources. Instead of giving a URL to a mailing list
 archive, summarize the relevant points of the discussion.
 
 
-(3) Generate your patch using Git tools out of your commits.
-
-
-Please make sure your patch does not add commented out debugging code,
-or include any extra files which do not relate to what your patch
-is trying to achieve. 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 "next" branch,
-that is fine, but please mark it as such.
-
-
-(4) Sending your patches.
+(3) Generate and send your patch to the Git mailing list
 
 People on the Git mailing list 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, each patch should be submitted
-"inline" in a separate message.
+"inline" (not as an attachment) in a separate message.
+
+There can be unexpected problems in sending patches:
+
+  . Webmail clients like Gmail generally corrupt whitespace in patches.
+  . messages using HTML-formatting (used by default in many webmail
+    clients) is automatically rejected by the Git mailing list server.
+
+Because of these factors, it's recommended that you use one of these
+specific methods to generate and send your patchs:
+
+  - Generate mail-ready patch files using "git format-patch" and
+    send them using "git send-email" to the Git mailing list.
+    See SubmittingPatchesByMUA for further details.
 
+  - Create a pull request on https://github.com/git/git and
+    use https://submitgit.herokuapp.com/ to send it as a patch series
+    to the mailing list.  Note that the PR is just the place where your
+    patch is born - discussion of the patch should still take place on
+    the Git mailing list.
 
+Please make sure to review your patch before sending it, to ensure that
+it:
 
+  . accurately reflects the change you want to make
+  . does not add commented-out debugging code, or include any extra
+    files which do not relate to what your patch is trying to achieve.
+  . cleanly applies to the "master" branch head.  If you are preparing
+    a work based on "next" branch, that is fine, but please mark it as
+    such.
 
 It is a common convention to prefix your subject line with
 [PATCH].  This lets people easily distinguish patches from other
@@ -186,7 +200,7 @@ patch.
      *2* The mailing list: git@vger.kernel.org
 
 
-(5) Sign your work
+(4) Sign your work
 
 To improve tracking of who did what, we've borrowed the
 "sign-off" procedure from the Linux kernel project on patches

--
https://github.com/git/git/pull/223

Re: [PATCH 1/2] Partition SubmittingPatches doc into two files

[Junio C Hamano]

Roberto Tyley <roberto.tyley@gmail.com> writes:

> Subject: Re: [PATCH 1/2] Partition SubmittingPatches doc into two files

That violates the first paragraph of "(2) Describe your changes
well."

	SubmittingPatches: separate parts specific to mailed-in	patches

or something like that, to

 - Prefix with the "area";
 - Summarize what you did in a way that makes it clear why.

> No editorial changes in this commit, the text that is transferred into the
> second file is unchanged apart from minor chunk re-ordering.
>
> The split is based on:
>
> * Information needed for all users, whether using `git send-email` or
>   submitGit (ie good commit practice, mailing list etiquette)
> * Information needed just for `git send-email`/MUA users (generating the
>   right kind of diff, avoid MIME & PGP, send-email & MUA specific hints)
> ---

Violates "(5) Sign your work"?

Re: [PATCH 2/2] Add submitGit patch-submission information

[Junio C Hamano]

Roberto Tyley <roberto.tyley@gmail.com> writes:

> +(3) Generate and send your patch to the Git mailing list
>  
>  People on the Git mailing list 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, each patch should be submitted
> -"inline" in a separate message.
> +"inline" (not as an attachment) in a separate message.
> +
> +There can be unexpected problems in sending patches:
> +
> +  . Webmail clients like Gmail generally corrupt whitespace in patches.
> +  . messages using HTML-formatting (used by default in many webmail
> +    clients) is automatically rejected by the Git mailing list server.
> +
> +Because of these factors, it's recommended that you use one of these
> +specific methods to generate and send your patchs:

Perhaps:

    It's recommended ... your patches, unless you already know how
    to correctly send your patches as plain-text e-mails.

That is, the ones listed below are known to produce good patches,
but our recommendation is _so_ strong to urge users with working
set-up to migrate to them.

> +
> +  - Generate mail-ready patch files using "git format-patch" and
> +    send them using "git send-email" to the Git mailing list.
> +    See SubmittingPatchesByMUA for further details.
>  
> +  - Create a pull request on https://github.com/git/git and
> +    use https://submitgit.herokuapp.com/ to send it as a patch series
> +    to the mailing list.  Note that the PR is just the place where your
> +    patch is born - discussion of the patch should still take place on
> +    the Git mailing list.

This is a tangent but I am wondering if you can do this _without_
creating a pull request to that repository.  I have a watch on that
repository and my notification gets unnecessarily large because of
these pull requests that were made _only_ for submitGit.  Can't
submitGit be taught to take a branch in a repository of the
submitter as input, (instead of a pull request to that public
repository)?

Once it is done, you do not even have to say "Note that", as there
is no room for confusion.

> +Please make sure to review your patch before sending it, to ensure that
> +it:
>  
> +  . accurately reflects the change you want to make
> +  . does not add commented-out debugging code, or include any extra
> +    files which do not relate to what your patch is trying to achieve.
> +  . cleanly applies to the "master" branch head.  If you are preparing
> +    a work based on "next" branch, that is fine, but please mark it as
> +    such.
>  
>  It is a common convention to prefix your subject line with
>  [PATCH].  This lets people easily distinguish patches from other
> @@ -186,7 +200,7 @@ patch.
>       *2* The mailing list: git@vger.kernel.org
>  
>  
> -(5) Sign your work
> +(4) Sign your work
>  
>  To improve tracking of who did what, we've borrowed the
>  "sign-off" procedure from the Linux kernel project on patches
>
> --
> https://github.com/git/git/pull/223

Re: [PATCH 2/2] Add submitGit patch-submission information

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

>> +Because of these factors, it's recommended that you use one of these
>> +specific methods to generate and send your patchs:
>
> Perhaps:
>
>     It's recommended ... your patches, unless you already know how
>     to correctly send your patches as plain-text e-mails.
>
> That is, the ones listed below are known to produce good patches,
> but our recommendation is _so_ strong to urge users with working

Well, I meant "our recommendation is *not* so strong" here.

Re: [PATCH 2/2] Add submitGit patch-submission information

[Jeff King]

On Thu, Apr 14, 2016 at 03:27:18PM -0700, Junio C Hamano wrote:

> > +  - Create a pull request on https://github.com/git/git and
> > +    use https://submitgit.herokuapp.com/ to send it as a patch series
> > +    to the mailing list.  Note that the PR is just the place where your
> > +    patch is born - discussion of the patch should still take place on
> > +    the Git mailing list.
> 
> This is a tangent but I am wondering if you can do this _without_
> creating a pull request to that repository.  I have a watch on that
> repository and my notification gets unnecessarily large because of
> these pull requests that were made _only_ for submitGit.  Can't
> submitGit be taught to take a branch in a repository of the
> submitter as input, (instead of a pull request to that public
> repository)?

Yeah, I have noticed that, too. It creates a lot of noise in my
notification feed (which I process by email), to the point that I'll
probably un-watch git/git.

-Peff