Subject: Re: [bug#74046] [PATCH v2] doc: Add "Contributing to Guix's infrastructure".

From: Ludovic Courtès <[email-masked]>
Date: Wed, 20 Nov 2024 23:28:14 +0100

Hi!

Ekaitz Zarraga <[email-masked]> skribis:

> Use the "Call for contribution to the Guix infrastructure" by Ludovic
> Courtès to create a section in the documentation that describes how to
> contribute to the infrastructure.
>
> https://lists.gnu.org/archive/html/guix-devel/2024-05/msg00183.html
>
> * doc/contributing.texi (Contributing to Guix's infrastructure): New
>   section.
>
> Change-Id: I3f3a99ad884110cc8323789e8c14bec1f7327e97

I think it’s a good idea.  I have some reservations about the style, as
Greg already noted :-), and the fact that some of the info is quite
detailed and might become outdated rather quickly.  But I think the
result is still a big improvement, and that outweighs the “risks”.

> +@node Contributing to Guix's infrastructure
> +@section Contributing to Guix's infrastructure

Nitpick: Could you use title case for all section/node titles?

> +@itemize
> +@item Build Farm Front-End: @url{https://git.cbaines.net/guix/bffe}
> +@item Cuirass: @url{https://guix.gnu.org/cuirass/}

To improve rendering, especially in HTML, could you use two-argument
@url as shown below, for all the URLs?

  @url{https://guix.gnu.org/cuirass/, Cuirass}

> +Prerequisite: Being a “known” member of the community, familiarity with Guix
> +System administration, with some of the services/web sites being run, and with
> +the infrastructure handbook:
> +
> +@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/infra-handbook.org}

the
@uref{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/infra-handbook.org,
infrastructure handbook}.

> +We need hosting of “small” machines such as single-board computers (AArch64,

Quotes should be written ``like this'' to make sure nothing goes wrong
with the various Texinfo backends.

Could you send an updated version?

Thanks!

Ludo’.

PS: At some point we should prolly consider make the “Contributing”
    chapter to a separate document altogether.