bug#66319: Incorrect code snippet in manual

[John Kehayias via Bug reports for GNU Guix <bug-guix@gnu.org>]

Hi Gabriel,

On Mon, Oct 02, 2023 at 06:38 PM, Gabriel Hondet wrote:

> Hello,
>
> The code snippets of the page 'Sending a patch series' look incorrect to
> me: the snippets mention the email address
> "guix-patches@debbugs.gnu.org" but the text mentions
> "guix-patches@gnu.org".
>

It is possible that one is an alias for the other (I'm not sure), but as
far as I know I always use the guix-patches@gnu.org address to start a
patch submission. After the initial email, as noted in the manual, you
get a bug number @debbugs.gnu.org to use.

> For instance,
>> We can now send just the cover letter to the guix-patches@gnu.org
>> address, which will create an issue that we can send the rest of the
>> patches to.
>>
>> > $ git send-email outgoing/0000-cover-letter.patch -a \
>> >       --to=guix-patches@debbugs.gnu.org \
>> >       $(etc/teams.scm cc-members ...)
>> > $ rm outgoing/0000-cover-letter.patch # we don't want to resend it!
>
> The documentation I'm looking at is the one accessible at
> https://guix.gnu.org/manual/en/html_node/Sending-a-Patch-Series.html#Multiple-Patches
> on the Monday, 2nd of October at 6pm (CEST) (a.k.a. 2023-10-02T18+02:00
> if you prefer ISO dates).
>

Ah, so this is the "1.4.0" manual rather than the current one:
<https://guix.gnu.org/en/manual/devel/en/html_node/Sending-a-Patch-Series.html#Multiple-Patches-1>.
This is a long standing confusion that needs to be sorted out, but in
short I would say the 1.4.0 manual is just to match the 1.4.0 installer,
but once installed and updated you should always use the manual that
matches your guix version. You can use "info guix" for instance, or the
web "devel" manual for the latest version.

So, yes, this is a potential error in the 1.4.0 manual but is corrected
in the current version. I don't think we can easily correct the old
version (it is already tagged and released) but we do have to clarify
the manual online for what version is what. This has been reported
before and there are some proposals, not sure why it hasn't been done
yet. Sorry about that!

> Cheers,
> Gabriel

Hope that is helpful! I'm going to close this in light of the above, but
feel free (or someone else) to reopen if needed.

Thanks for the close reading, doc errors and suggestions always welcome!

John