[bug#28491] [PATCH] doc: Add "Sending a Patch Series" subsection.

[bug#28491] [PATCH] doc: Add "Sending a Patch Series" subsection.

[Jan Nieuwenhuizen]

Searching for `git send-email' took you to the end of `Submitting Patches'
section which said

   You may use your email client or the ‘git send-email’ command.

without further warning or remark.

* doc/contributing.texi (Sending a Patch Series): Move information about
debbugs bug 15361 to subsection.  Add git-send-email index entries.
(Submitting Patches): Reference it.
---
 doc/contributing.texi | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 00edd4771..71a465a37 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -298,11 +298,7 @@ This mailing list is backed by a Debbugs instance accessible at
 of submissions.  Each message sent to that mailing list gets a new
 tracking number assigned; people can then follow up on the submission by
 sending email to @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is
-the tracking number.  When sending a patch series, please first send one
-message to @email{guix-patches@@gnu.org}, and then send subsequent
-patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure they are kept
-together.  See @uref{https://debbugs.gnu.org/Advanced.html, the Debbugs
-documentation}, for more information.
+the tracking number, @xref{Sending a Patch Series}.
 
 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
 standards, GNU Coding Standards}); you can check the commit history for
@@ -434,7 +430,22 @@ Please follow our code formatting rules, possibly running the
 
 When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
 a subject.  You may use your email client or the @command{git
-send-email} command.  We prefer to get patches in plain text messages,
-either inline or as MIME attachments.  You are advised to pay attention if
-your email client changes anything like line breaks or indentation which
-could potentially break the patches.
+send-email} command @xref{Sending a Patch Series}.  We prefer to get
+patches in plain text messages, either inline or as MIME attachments.
+You are advised to pay attention if your email client changes anything
+like line breaks or indentation which could potentially break the
+patches.
+
+@unnumberedsubsec Sending a Patch Series
+@anchor{Sending a Patch Series}
+@cindex patch series
+@cindex @code{git send-email}
+@cindex @code{git-send-email}
+
+When sending a patch series (e.g., using @code{git send-email}), please
+first send one message to @email{guix-patches@@gnu.org}, and then send
+subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
+they are kept together.  See
+@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
+for more information.
+@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
-- 
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com

[bug#28491] [PATCH] doc: Add "Sending a Patch Series" subsection.

[Nicolas Goaziou]

Hello,

Jan Nieuwenhuizen <janneke@gnu.org> writes:

> +the tracking number, @xref{Sending a Patch Series}.

It should be @pxref.

Regards,

-- 
Nicolas Goaziou                                                0x80A93738

[bug#28491] [PATCH] doc: Add "Sending a Patch Series" subsection.

[Jan Nieuwenhuizen]

[-- Attachment #1: Type: text/plain, Size: 239 bytes --]

Nicolas Goaziou writes:

>> +the tracking number, @xref{Sending a Patch Series}.
>
> It should be @pxref.

Thanks, changed both instances from @xref{} to (@pxref{..}), similar to
other usage.

Updated version attached

Greetings,
janneke


[-- Attachment #2: 0001-doc-Add-Sending-a-Patch-Series-subsection.patch --]
[-- Type: text/x-patch, Size: 3331 bytes --]

From 12b798f59e7d1397e1581f52a5321d5880cb33c1 Mon Sep 17 00:00:00 2001
From: Jan Nieuwenhuizen <janneke@gnu.org>
Date: Mon, 18 Sep 2017 11:12:43 +0200
Subject: [PATCH] doc: Add "Sending a Patch Series" subsection.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Searching for `git send-email' took you to the end of `Submitting Patches'
section which said

   You may use your email client or the ‘git send-email’ command.

without further warning or remark.

* doc/contributing.texi (Sending a Patch Series): Move information about
debbugs bug 15361 to subsection.  Add git-send-email index entries.
(Submitting Patches): Reference it.
---
 doc/contributing.texi | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 00edd4771..323b01628 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -298,11 +298,7 @@ This mailing list is backed by a Debbugs instance accessible at
 of submissions.  Each message sent to that mailing list gets a new
 tracking number assigned; people can then follow up on the submission by
 sending email to @code{@var{NNN}@@debbugs.gnu.org}, where @var{NNN} is
-the tracking number.  When sending a patch series, please first send one
-message to @email{guix-patches@@gnu.org}, and then send subsequent
-patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure they are kept
-together.  See @uref{https://debbugs.gnu.org/Advanced.html, the Debbugs
-documentation}, for more information.
+the tracking number (@pxref{Sending a Patch Series}).
 
 Please write commit logs in the ChangeLog format (@pxref{Change Logs,,,
 standards, GNU Coding Standards}); you can check the commit history for
@@ -434,7 +430,22 @@ Please follow our code formatting rules, possibly running the
 
 When posting a patch to the mailing list, use @samp{[PATCH] @dots{}} as
 a subject.  You may use your email client or the @command{git
-send-email} command.  We prefer to get patches in plain text messages,
-either inline or as MIME attachments.  You are advised to pay attention if
-your email client changes anything like line breaks or indentation which
-could potentially break the patches.
+send-email} command (@pxref{Sending a Patch Series}).  We prefer to get
+patches in plain text messages, either inline or as MIME attachments.
+You are advised to pay attention if your email client changes anything
+like line breaks or indentation which could potentially break the
+patches.
+
+@unnumberedsubsec Sending a Patch Series
+@anchor{Sending a Patch Series}
+@cindex patch series
+@cindex @code{git send-email}
+@cindex @code{git-send-email}
+
+When sending a patch series (e.g., using @code{git send-email}), please
+first send one message to @email{guix-patches@@gnu.org}, and then send
+subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
+they are kept together.  See
+@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
+for more information.
+@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html
-- 
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com


[-- Attachment #3: Type: text/plain, Size: 152 bytes --]


-- 
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com

[bug#28491] [PATCH] doc: Add "Sending a Patch Series" subsection.

[Nicolas Goaziou]

Jan Nieuwenhuizen <janneke@gnu.org> writes:

> Thanks, changed both instances from @xref{} to (@pxref{..}), similar to
> other usage.

Looks good. @pxref after a comma was fine, too.

> +When sending a patch series (e.g., using @code{git send-email}), please
> +first send one message to @email{guix-patches@@gnu.org}, and then send
> +subsequent patches to @email{@var{NNN}@@debbugs.gnu.org} to make sure
> +they are kept together.  See
> +@uref{https://debbugs.gnu.org/Advanced.html, the Debbugs documentation}
> +for more information.
> +@c Debbugs bug: https://debbugs.gnu.org/db/15/15361.html

Would it make sense to recall the need to close the thread by answering
to <mailto:done-NNN@debbugs.gnu.org>? This information is surprisingly
hard to find.


Regards,

[bug#28491] [PATCH] doc: Add "Sending a Patch Series" subsection.

[Jan Nieuwenhuizen]

[-- Attachment #1: Type: text/plain, Size: 321 bytes --]

Nicolas Goaziou writes:

> Looks good. @pxref after a comma was fine, too.

Ok.

> Would it make sense to recall the need to close the thread by answering
> to <mailto:done-NNN@debbugs.gnu.org>? This information is surprisingly
> hard to find.

Yes, I think so.  Added as a second patch, how is this?

Greeting,
janneke


[-- Attachment #2: 0002-doc-Add-a-note-about-closing-bug-threads.patch --]
[-- Type: text/x-patch, Size: 1175 bytes --]

From 73cb6cc69746c03efd5ea3c233a74717a6612534 Mon Sep 17 00:00:00 2001
From: Jan Nieuwenhuizen <janneke@gnu.org>
Date: Mon, 18 Sep 2017 17:25:58 +0200
Subject: [PATCH 2/2] doc: Add a note about closing bug threads.

* doc/contributing.texi (Submitting Patches): Add a note about closing bug
threads by mailing to NNN-done@debbugs.gnu.org.

Suggested-by: Nicolas Goaziou <mail@nicolasgoaziou.fr>
---
 doc/contributing.texi | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 323b01628..1b1875fa0 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -436,6 +436,9 @@ You are advised to pay attention if your email client changes anything
 like line breaks or indentation which could potentially break the
 patches.
 
+When a bug is resolved, please close the thread by sending an email to
+@email{@var{NNN}-done@@debbugs.gnu.org}.
+
 @unnumberedsubsec Sending a Patch Series
 @anchor{Sending a Patch Series}
 @cindex patch series
-- 
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com


[-- Attachment #3: Type: text/plain, Size: 152 bytes --]


-- 
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com

[bug#28491] [PATCH] doc: Add "Sending a Patch Series" subsection.

[Nicolas Goaziou]

Jan Nieuwenhuizen <janneke@gnu.org> writes:

> Nicolas Goaziou writes:
>
>> Would it make sense to recall the need to close the thread by answering
>> to <mailto:done-NNN@debbugs.gnu.org>? This information is surprisingly
>> hard to find.
>
> Yes, I think so.  Added as a second patch, how is this?

[...]

> * doc/contributing.texi (Submitting Patches): Add a note about closing bug
> threads by mailing to NNN-done@debbugs.gnu.org.

See, I got it backwards once again ;)

AFAIC, this all looks good. Thank you.

I'll let others comment about it.

Regards,

[bug#28491] [PATCH] doc: Add "Sending a Patch Series" subsection.

[Ludovic Courtès]

Nicolas Goaziou <mail@nicolasgoaziou.fr> skribis:

> Jan Nieuwenhuizen <janneke@gnu.org> writes:
>
>> Nicolas Goaziou writes:
>>
>>> Would it make sense to recall the need to close the thread by answering
>>> to <mailto:done-NNN@debbugs.gnu.org>? This information is surprisingly
>>> hard to find.
>>
>> Yes, I think so.  Added as a second patch, how is this?
>
> [...]
>
>> * doc/contributing.texi (Submitting Patches): Add a note about closing bug
>> threads by mailing to NNN-done@debbugs.gnu.org.

I’m fine with both patches, thank you!

In the future, we should probably add a “Reviewing Patches” section as
well.  :-)

Ludo’.

bug#28491: [PATCH] doc: Add "Sending a Patch Series" subsection.

[Jan Nieuwenhuizen]

Ludovic Courtès writes:

>>> * doc/contributing.texi (Submitting Patches): Add a note about closing bug
>>> threads by mailing to NNN-done@debbugs.gnu.org.
>
> I’m fine with both patches, thank you!

Thanks, pushed to master as 4619b59cb49c5356eaea4650dee3d4de929e082a

> In the future, we should probably add a “Reviewing Patches” section as
> well.  :-)

Yes...that should be easy to review ;-)
janneke

-- 
Jan Nieuwenhuizen <janneke@gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com