[PATCH] Documentation/SubmittingPatches: Instruct how to use [PATCH] Subject header

[PATCH] Documentation/SubmittingPatches: Instruct how to use [PATCH] Subject header

[Jari Aalto]

Suggest putting additional message inside brackets, like [PATCH v2]
for reworked content.

Signed-off-by: Jari Aalto <jari.aalto AT cante.net>
---
 Idea by Jakub Narebski

 Documentation/SubmittingPatches |    3 +++
 1 files changed, 3 insertions(+), 0 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index de08d09..69ecbd3 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -37,6 +37,9 @@ Checklist (and a short version for the impatient):
 	  maintainer (gitster@pobox.com). If you use
 	  git-send-email(1), please test it first by sending
 	  email to yourself.
+        - If you rework the patch, announce the message
+          in brackets. For example "[PATCH/RFC]", "[PATCH (resend)]",
+          "[PATCH v2]" etc.
 
 Long version:
 
-- 
1.5.4-rc5.GIT-dirty



-- 
Welcome to FOSS revolution: we fix and modify until it shines

Re: [PATCH] Documentation/SubmittingPatches: Instruct how to use [PATCH] Subject header

[Johannes Schindelin]

Hi,

On Mon, 4 Feb 2008, Jari Aalto wrote:

> @@ -37,6 +37,9 @@ Checklist (and a short version for the impatient):
>  	  maintainer (gitster@pobox.com). If you use
>  	  git-send-email(1), please test it first by sending
>  	  email to yourself.
> +        - If you rework the patch, announce the message
> +          in brackets. For example "[PATCH/RFC]", "[PATCH (resend)]",
> +          "[PATCH v2]" etc.

Whitespace error?  (Spaces instead of Tabs)

Ciao,
Dscho

Re: [PATCH] Documentation/SubmittingPatches: Instruct how to use [PATCH] Subject header

[Jari Aalto]

* Mon 2008-02-04 Johannes Schindelin <Johannes.Schindelin@gmx.de>
>
> Whitespace error?  (Spaces instead of Tabs)

There should be a big notice at the beginning of
Documentation/SubmittingPatches:

Junio, would you add this.

Jari

----------------------------------------------------------------
Checklist (and a short version for the impatient):

        General:

                NOTE: Please set your editor to use tabs instead of
                spaces. In Emacs this can be set with
                (setq indent-tabs-mode t) and in vi this can be set 
                with ...

        Commits:

-- 
Welcome to FOSS revolution: we fix and modify until it shines

Re: [PATCH] Documentation/SubmittingPatches: Instruct how to use [PATCH] Subject header

[Junio C Hamano]

Jari Aalto <jari.aalto@cante.net> writes:

> Suggest putting additional message inside brackets, like [PATCH v2]
> for reworked content.
>
> Signed-off-by: Jari Aalto <jari.aalto AT cante.net>
> ---
>  Idea by Jakub Narebski
>
>  Documentation/SubmittingPatches |    3 +++
>  1 files changed, 3 insertions(+), 0 deletions(-)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index de08d09..69ecbd3 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -37,6 +37,9 @@ Checklist (and a short version for the impatient):
>  	  maintainer (gitster@pobox.com). If you use
>  	  git-send-email(1), please test it first by sending
>  	  email to yourself.
> +        - If you rework the patch, announce the message
> +          in brackets. For example "[PATCH/RFC]", "[PATCH (resend)]",
> +          "[PATCH v2]" etc.
>  

This adds something to the "short version" that the full version
does not even talk about?

I do not think this needs to be in the short version, but an
update to the full version would indeed be a good idea.

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index de08d09..0661293 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -112,7 +112,12 @@ 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
-e-mail discussions.
+e-mail discussions.  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.
 
 "git format-patch" command follows the best current practice to
 format the body of an e-mail message.  At the beginning of the

[PATCH 1/2 (RFC)] Documentation/SubmittingPatches: discuss first then submit

[Junio C Hamano]

This is something I've had in mind for some time.  I get enough
e-mails as-is, and I suspect the workflow to get list members
involved would work better if we get the discussion concluded on
the list first before patches hit my tree (even 'next').

---
On top of the previous one to talk about [PATCH v2] and friends...

 Documentation/SubmittingPatches |   23 ++++++++++++++++-------
 1 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index cd80148..0661293 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -34,9 +34,9 @@ Checklist (and a short version for the impatient):
 	- 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 (gitster@pobox.com). If you use
-	  git-send-email(1), please test it first by sending
-	  email to yourself.
+	  maintainer (gitster@pobox.com) if (and only if) the patch
+	  is ready for inclusion. If you use git-send-email(1),
+	  please test it first by sending email to yourself.
 
 Long version:
 
@@ -162,7 +162,8 @@ 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.
+it "To:" the maintainer and optionally "cc:" the list for
+inclusion.
 
 Also note that your maintainer does not actively involve himself in
 maintaining what are in contrib/ hierarchy.  When you send fixes and

[PATCH 2/2] Documentation/SubmittingPatches: What's Acked-by and Tested-by?

[Junio C Hamano]

We used to talk about "internal company procedures", but this
document is about submitting patches to the git mailing list.

More useful information is when to say Acked-by: and Tested-by:.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/SubmittingPatches |   16 ++++++++++++----
 1 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 7900223..0661293 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -216,10 +216,18 @@ then you just add a line saying
 This line can be automatically added by git if you run the git-commit
 command with the -s option.
 
-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.
-
+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).
+
+Some people also put extra tags at the end.
+
+"Acked-by:" says that the patch was reviewed by the 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