# [PATCH] Documentation/SubmittingPatches: Instruct how to use [PATCH] Subject header 6 messages from 2008-02-04 to 2008-02-04. Participants: Jari Aalto, Johannes Schindelin, Junio C Hamano. Thread: https://gitlist.dev/t/11861 ## Jari Aalto, 2008-02-04 00:24 Subject: [PATCH] Documentation/SubmittingPatches: Instruct how to use [PATCH] Subject header Message-ID: URL: https://gitlist.dev/e/r6ft1sd1.fsf%40blue.sea.net ``` Suggest putting additional message inside brackets, like [PATCH v2] for reworked content. Signed-off-by: Jari Aalto --- 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 ``` ## Johannes Schindelin, 2008-02-04 00:29 Subject: Re: [PATCH] Documentation/SubmittingPatches: Instruct how to use [PATCH] Subject header Message-ID: URL: https://gitlist.dev/e/alpine.LSU.1.00.0802040029020.7372%40racer.site In-Reply-To: ``` 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 ``` ## Junio C Hamano, 2008-02-04 00:55 Subject: Re: [PATCH] Documentation/SubmittingPatches: Instruct how to use [PATCH] Subject header Message-ID: <7v7ihlpmkm.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7v7ihlpmkm.fsf%40gitster.siamese.dyndns.org In-Reply-To: ``` Jari Aalto writes: > Suggest putting additional message inside brackets, like [PATCH v2] > for reworked content. > > Signed-off-by: Jari Aalto > --- > 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 ``` ## Junio C Hamano, 2008-02-04 01:00 Subject: [PATCH 1/2 (RFC)] Documentation/SubmittingPatches: discuss first then submit Message-ID: <7v3as9pmcf.fsf_-_@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7v3as9pmcf.fsf_-_%40gitster.siamese.dyndns.org In-Reply-To: <7v7ihlpmkm.fsf@gitster.siamese.dyndns.org> ``` 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 ``` ## Junio C Hamano, 2008-02-04 01:02 Subject: [PATCH 2/2] Documentation/SubmittingPatches: What's Acked-by and Tested-by? Message-ID: <7vwsplo7ob.fsf_-_@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vwsplo7ob.fsf_-_%40gitster.siamese.dyndns.org In-Reply-To: <7v7ihlpmkm.fsf@gitster.siamese.dyndns.org> ``` 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 --- 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 ``` ## Jari Aalto, 2008-02-04 08:12 Subject: Re: [PATCH] Documentation/SubmittingPatches: Instruct how to use [PATCH] Subject header Message-ID: URL: https://gitlist.dev/e/ejbt16ox.fsf%40blue.sea.net In-Reply-To: ``` * Mon 2008-02-04 Johannes Schindelin > > 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 ```