Bogus ‘etc/teams.scm’ usage recommendations?

Bogus ‘etc/teams.scm’ usage recommendations?

[Ludovic Courtès]

Hello Guix!

The manual recommends this (info "(guix) Teams"):

  git send-email --to ISSUE_NUMBER@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch

where:

--8<---------------cut here---------------start------------->8---
λ ./etc/teams.scm cc mentors
--add-header="X-Debbugs-Cc: rg@raghavgururajan.name" --add-header="X-Debbugs-Cc: zimon.toutoune@gmail.com" …
--8<---------------cut here---------------end--------------->8---

I believe this cannot work because the shell will split words on each
whitespace; IOW, the double quotes above do not have the desired effect.

The second issue is that passing ‘--add-header’ to ‘git send-email’
seems to have no effect.  AIUI, ‘git send-email’ passes those to ‘git
format-patch’, except that it has no reason to invoke it, right?

Maybe I’m missing something but it looks like we have documentation to
improve.  Thoughts?

Ludo’.

Re: Bogus ‘etc/teams.scm’ usage recommendations?

[Simon Tournier]

Hi Ludo,

On Tue, 03 Jan 2023 at 23:29, Ludovic Courtès <ludo@gnu.org> wrote:

> The manual recommends this (info "(guix) Teams"):
>
>   git send-email --to ISSUE_NUMBER@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
>
> where:
>
> --8<---------------cut here---------------start------------->8---
> λ ./etc/teams.scm cc mentors
> --add-header="X-Debbugs-Cc: rg@raghavgururajan.name" --add-header="X-Debbugs-Cc: zimon.toutoune@gmail.com" …
> --8<---------------cut here---------------end--------------->8---
>
> I believe this cannot work because the shell will split words on each
> whitespace; IOW, the double quotes above do not have the desired effect.

Well, IIUC, this part is tracked by #58813 [1].

1: <http://issues.guix.gnu.org/issue/58813>


Cheers,
simon

Re: Bogus ‘etc/teams.scm’ usage recommendations?

[Maxim Cournoyer]

+CC 58813@debbugs.gnu.org

Hi,

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi Ludo,
>
> On Tue, 03 Jan 2023 at 23:29, Ludovic Courtès <ludo@gnu.org> wrote:
>
>> The manual recommends this (info "(guix) Teams"):
>>
>>   git send-email --to ISSUE_NUMBER@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
>>
>> where:
>>
>> --8<---------------cut here---------------start------------->8---
>> λ ./etc/teams.scm cc mentors
>> --add-header="X-Debbugs-Cc: rg@raghavgururajan.name"
>> --add-header="X-Debbugs-Cc: zimon.toutoune@gmail.com" …
>> --8<---------------cut here---------------end--------------->8---
>>
>> I believe this cannot work because the shell will split words on each
>> whitespace; IOW, the double quotes above do not have the desired effect.

> Well, IIUC, this part is tracked by #58813 [1].
>
> 1: <http://issues.guix.gnu.org/issue/58813>

Indeed (CC'd).

I thought about not using whitespace in the generated output, but I'm
not sure if Debbugs or email clients in general would care, plus it's a
dirty fix.

With the recent patman integration merged (though do apply #60576 as a
fixup commit), I'm tempted to remove the mentions of git send-email
$(etc/teams.scm cc-members ...) and replace that by 'Further automation
of git send-email and etc/teams.scm is possible via the patman package'.

What do you think?

-- 
Thanks,
Maxim

bug#58813: Bogus ‘etc/teams.scm’ usage recommendations?

[Maxim Cournoyer]

+CC 58813@debbugs.gnu.org

Hi,

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi Ludo,
>
> On Tue, 03 Jan 2023 at 23:29, Ludovic Courtès <ludo@gnu.org> wrote:
>
>> The manual recommends this (info "(guix) Teams"):
>>
>>   git send-email --to ISSUE_NUMBER@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
>>
>> where:
>>
>> --8<---------------cut here---------------start------------->8---
>> λ ./etc/teams.scm cc mentors
>> --add-header="X-Debbugs-Cc: rg@raghavgururajan.name"
>> --add-header="X-Debbugs-Cc: zimon.toutoune@gmail.com" …
>> --8<---------------cut here---------------end--------------->8---
>>
>> I believe this cannot work because the shell will split words on each
>> whitespace; IOW, the double quotes above do not have the desired effect.

> Well, IIUC, this part is tracked by #58813 [1].
>
> 1: <http://issues.guix.gnu.org/issue/58813>

Indeed (CC'd).

I thought about not using whitespace in the generated output, but I'm
not sure if Debbugs or email clients in general would care, plus it's a
dirty fix.

With the recent patman integration merged (though do apply #60576 as a
fixup commit), I'm tempted to remove the mentions of git send-email
$(etc/teams.scm cc-members ...) and replace that by 'Further automation
of git send-email and etc/teams.scm is possible via the patman package'.

What do you think?

-- 
Thanks,
Maxim

Re: bug#58813: can't substitute etc/teams.scm command as doc suggests

[Ludovic Courtès]

Hi,

Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:

> Simon Tournier <zimon.toutoune@gmail.com> writes:
>
>> Hi Ludo,
>>
>> On Tue, 03 Jan 2023 at 23:29, Ludovic Courtès <ludo@gnu.org> wrote:
>>
>>> The manual recommends this (info "(guix) Teams"):
>>>
>>>   git send-email --to ISSUE_NUMBER@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
>>>
>>> where:
>>>
>>> --8<---------------cut here---------------start------------->8---
>>> λ ./etc/teams.scm cc mentors
>>> --add-header="X-Debbugs-Cc: rg@raghavgururajan.name"
>>> --add-header="X-Debbugs-Cc: zimon.toutoune@gmail.com" …
>>> --8<---------------cut here---------------end--------------->8---
>>>
>>> I believe this cannot work because the shell will split words on each
>>> whitespace; IOW, the double quotes above do not have the desired effect.
>
>> Well, IIUC, this part is tracked by #58813 [1].
>>
>> 1: <http://issues.guix.gnu.org/issue/58813>
>
> Indeed (CC'd).
>
> I thought about not using whitespace in the generated output, but I'm
> not sure if Debbugs or email clients in general would care, plus it's a
> dirty fix.

Right.

How about just outputting a line like:

  X-Debbugs-Cc: maxim@example.org, ludo@example.org

that people would paste in their cover letter?

How do Linux’s scripts work?

> With the recent patman integration merged (though do apply #60576 as a
> fixup commit), I'm tempted to remove the mentions of git send-email
> $(etc/teams.scm cc-members ...) and replace that by 'Further automation
> of git send-email and etc/teams.scm is possible via the patman package'.
>
> What do you think?

This is the first time I hear about patman.  :-)

The “Submitting Patches” section mentions ‘git send-email’; I don’t
think this is about to change, is it?

Thanks,
Ludo’.

Re: bug#58813: can't substitute etc/teams.scm command as doc suggests

[Maxim Cournoyer]

Hi Ludovic,

Ludovic Courtès <ludo@gnu.org> writes:

> Hi,
>
> Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:
>
>> Simon Tournier <zimon.toutoune@gmail.com> writes:
>>
>>> Hi Ludo,
>>>
>>> On Tue, 03 Jan 2023 at 23:29, Ludovic Courtès <ludo@gnu.org> wrote:
>>>
>>>> The manual recommends this (info "(guix) Teams"):
>>>>
>>>>   git send-email --to ISSUE_NUMBER@debbugs.gnu.org $(./etc/teams.scm cc mentors) *.patch
>>>>
>>>> where:
>>>>
>>>> --8<---------------cut here---------------start------------->8---
>>>> λ ./etc/teams.scm cc mentors
>>>> --add-header="X-Debbugs-Cc: rg@raghavgururajan.name"
>>>> --add-header="X-Debbugs-Cc: zimon.toutoune@gmail.com" …
>>>> --8<---------------cut here---------------end--------------->8---
>>>>
>>>> I believe this cannot work because the shell will split words on each
>>>> whitespace; IOW, the double quotes above do not have the desired effect.
>>
>>> Well, IIUC, this part is tracked by #58813 [1].
>>>
>>> 1: <http://issues.guix.gnu.org/issue/58813>
>>
>> Indeed (CC'd).
>>
>> I thought about not using whitespace in the generated output, but I'm
>> not sure if Debbugs or email clients in general would care, plus it's a
>> dirty fix.
>
> Right.
>
> How about just outputting a line like:
>
>   X-Debbugs-Cc: maxim@example.org, ludo@example.org
>
> that people would paste in their cover letter?

Yes, that's better.

> How do Linux’s scripts work?

I think the scripts just print stuff at the terminal and expect the user
to copy paste.  Patman can be used to provide automation on top of that.

>> With the recent patman integration merged (though do apply #60576 as a
>> fixup commit), I'm tempted to remove the mentions of git send-email
>> $(etc/teams.scm cc-members ...) and replace that by 'Further automation
>> of git send-email and etc/teams.scm is possible via the patman package'.
>>
>> What do you think?
>
> This is the first time I hear about patman.  :-)
>
> The “Submitting Patches” section mentions ‘git send-email’; I don’t
> think this is about to change, is it?

It wouldn't change; patman would be hinted at briefly with a reference
to its documentation (info '(u-boot) Patman patch manager' from the
u-boot-documentation package) as a nice way to stay organize with
submissions and automate a few things on top of git send-email.

-- 
Thanks,
Maxim

Re: bug#58813: can't substitute etc/teams.scm command as doc suggests

[Simon Tournier]

Hi,

On Mon, 09 Jan 2023 at 15:52, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:

> It wouldn't change; patman would be hinted at briefly with a reference
> to its documentation (info '(u-boot) Patman patch manager' from the
> u-boot-documentation package) as a nice way to stay organize with
> submissions and automate a few things on top of git send-email.

Is it possible to read online patman documentation?  I am not able to
find one.  Moreover, it could ease the adoption if a minimal sample of
such configuration is provided.  A minimal out of the box configuration
as starter.

On my side, if I have to do more than just click to read documentation,
then I give up.  And then, if I have to parse lengthy documentation,
then it depends on my motivation but it is also possible that I give
up–the well-known RTFM trap.  In other words, I am lazy. :-)

Cheers,
simon

Re: bug#58813: can't substitute etc/teams.scm command as doc suggests

[Maxim Cournoyer]

Hi Simon,

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi,
>
> On Mon, 09 Jan 2023 at 15:52, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:
>
>> It wouldn't change; patman would be hinted at briefly with a reference
>> to its documentation (info '(u-boot) Patman patch manager' from the
>> u-boot-documentation package) as a nice way to stay organize with
>> submissions and automate a few things on top of git send-email.
>
> Is it possible to read online patman documentation?  I am not able to
> find one.

It's developed as part of U-Boot and available at
https://u-boot.readthedocs.io/en/latest/develop/patman.html.  It's
generated from the same sources as the info manual from
u-boot-documentation referenced above.

> Moreover, it could ease the adoption if a minimal sample of
> such configuration is provided.  A minimal out of the box configuration
> as starter.

No configuration is required other than the .patman file already checked
in Guix.

> On my side, if I have to do more than just click to read documentation,
> then I give up.  And then, if I have to parse lengthy documentation,
> then it depends on my motivation but it is also possible that I give
> up–the well-known RTFM trap.  In other words, I am lazy. :-)

The 'Patman patch manager' section is relatively compact; I read it from
the comfort of Emacs ;-).  There's also some alternative short text
available as 'patman -H' if you are in a hurry.

-- 
Thanks,
Maxim

Re: bug#58813: can't substitute etc/teams.scm command as doc suggests

[Simon Tournier]

Hi Maxim,

On mer., 11 janv. 2023 at 22:00, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:

> It's developed as part of U-Boot and available at
> https://u-boot.readthedocs.io/en/latest/develop/patman.html.  It's
> generated from the same sources as the info manual from
> u-boot-documentation referenced above.

Oh thanks!  I do not know why I did not found it when using my favorite
search engine. :-)

>> On my side, if I have to do more than just click to read documentation,
>> then I give up.  And then, if I have to parse lengthy documentation,
>> then it depends on my motivation but it is also possible that I give
>> up–the well-known RTFM trap.  In other words, I am lazy. :-)
>
> The 'Patman patch manager' section is relatively compact; I read it from
> the comfort of Emacs ;-).  There's also some alternative short text
> available as 'patman -H' if you are in a hurry.

Well, I still think that examples about how to use it are worth and will
help for adoption. :-)

For instance, this section of the manual [1] describes how to use
git-format-patch and git-send-email with details applied to Guix
examples.  It appears to me better than just pointing [2] and [3]. ;-)


1: <https://guix.gnu.org/manual/devel/en/guix.html#Sending-a-Patch-Series>
2: <https://git-scm.com/docs/git-format-patch>
3: <https://git-scm.com/docs/git-send-email>

Cheers,
simon