threads / patch / 11861

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

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

## tl;dr

6 messages between Feb 4, 2008 and Feb 4, 2008. Diffs are folded; open one to read it.

replies: 5people: 3as markdown or json

Jari Aalto· Feb 4, 2008, 00:24 UTC · lore

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(-)

Show changes to Documentation/SubmittingPatches +3 −0

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

Johannes Schindelin· Feb 4, 2008, 00:29 UTC · re: Jari Aalto · lore

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

Hi,

On Mon, 4 Feb 2008, Jari Aalto wrote:

Show 7 quoted lines

> @@ -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

Jari Aalto· Feb 4, 2008, 08:12 UTC · re: Johannes Schindelin · lore

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

* 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

Junio C Hamano· Feb 4, 2008, 00:55 UTC · re: Jari Aalto · lore

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

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

Show 22 quoted lines

> 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.

Show changes to Documentation/SubmittingPatches +6 −1

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

Junio C Hamano· Feb 4, 2008, 01:00 UTC · re: Junio C Hamano · lore

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

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(-)

Show changes to Documentation/SubmittingPatches +5 −4

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

Junio C Hamano· Feb 4, 2008, 01:02 UTC · re: Junio C Hamano · lore

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

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(-)

Show changes to Documentation/SubmittingPatches +12 −4

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