diff mbox series

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

Message ID e661d69afb3a40516403cc722ecbbe73639d3892.1730970238.git.ekaitz@elenq.tech
State New
Headers show
Series [bug#74046,v2] doc: Add "Contributing to Guix's infrastructure". | expand

Commit Message

Ekaitz Zarraga Nov. 7, 2024, 9:03 a.m. UTC
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
---
 doc/contributing.texi | 186 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 186 insertions(+)


base-commit: 091131af64fd4e4e925fff829fa19097cfcdfcc5

Comments

Ludovic Courtès Nov. 20, 2024, 10:28 p.m. UTC | #1
Hi!

Ekaitz Zarraga <ekaitz@elenq.tech> 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.
diff mbox series

Patch

diff --git a/doc/contributing.texi b/doc/contributing.texi
index acdc303be6..1fb6ce2e1e 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -37,6 +37,7 @@  Contributing
 * Deprecation Policy::          Commitments and tools for deprecation.
 * Writing Documentation::       Improving documentation in GNU Guix.
 * Translating Guix::            Make Guix speak your native language.
+* Contributing to Guix's infrastructure::  Make Guix ecosystem work better.
 @end menu
 
 @node Requirements
@@ -3594,3 +3595,188 @@  Translating Guix
       be updated accordingly (see @file{website/i18n-howto.txt} for more
       information on the process).
 @end itemize
+
+
+@cindex infrastructure
+@node Contributing to Guix's infrastructure
+@section Contributing to Guix's infrastructure
+
+Since its inception, the Guix project has always valued its autonomy, and that
+reflects in its infrastructure: our servers run Guix System and exclusively
+free software, and are administered by volunteers.
+
+Of course this comes at a cost and this is why we need contributions.  Our hope
+is to make infrastructure-related activity more legible so that maybe you can
+picture yourself helping in one of these areas.
+
+
+@menu
+* Coding::
+* System administration::
+* Day-to-day system administration::
+* On-site intervention::
+* Hosting::
+* Administrative tasks::
+@end menu
+
+@node Coding
+@subsection Coding
+
+Guix runs many Guix-specific services; this is all lovely Scheme code but it
+tends to receive less attention than Guix itself:
+
+@itemize
+@item Build Farm Front-End: @url{https://git.cbaines.net/guix/bffe}
+@item Cuirass: @url{https://guix.gnu.org/cuirass/}
+@item Goggles (IRC logger):
+@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/hydra/goggles.scm}
+@item Guix Build Coordinator:
+@url{https://git.savannah.gnu.org/cgit/guix/build-coordinator.git/}
+@item Guix Data Service:
+@url{https://git.savannah.gnu.org/git/guix/data-service.git/}
+@item Guix Packages Website:
+@url{https://codeberg.org/luis-felipe/guix-packages-website.git}
+@item mumi: @url{https://git.savannah.gnu.org/cgit/guix/mumi.git/}
+@item nar-herder: @url{https://git.savannah.gnu.org/cgit/guix/nar-herder.git/}
+@item QA Frontpage: @url{https://git.savannah.gnu.org/git/guix/qa-frontpage.git}
+@end itemize
+
+There is no time constraint on this coding activity: any improvement is
+welcome, whenever it comes.  Most of these code bases are relatively small,
+which should make it easier to get started.
+
+Prerequisites: Familiarity with Guile, HTTP, and databases.
+
+If you wish to get started, check out the README of the project of your choice
+and get in touch with guix-devel and the primary developer(s) of the tool as
+per @code{git shortlog -s | sort -k1 -n}.
+
+@node System administration
+@subsection System administration
+
+Guix System configuration for all our systems is held in this repository:
+
+@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/hydra/}
+
+The two front-ends are @file{berlin.scm} (the machine behind ci.guix.gnu.org)
+and @file{bayfront.scm} (the machine behind bordeaux.guix.gnu.org,
+guix.gnu.org, hpc.guix.info, qa.guix.gnu.org, and more).  Both connect to a
+number of build machines and helpers.
+
+Without even having SSH access to the machine, you can help by posting patches
+to improve the configuration (you can test it with @code{guix system vm}).
+Here are ways you can help:
+
+@itemize
+@item
+Improve infra monitoring: set up a dashboard to monitor all the infrastructure,
+and an out-of-band channel to communicate about downtime.
+
+@item
+Implement web site redundancy: guix.gnu.org should be backed by several
+machines on different sites.  Get in touch with us and/or send a patch!
+
+@item
+Implement substitute redundancy: likewise, bordeaux.guix.gnu.org and
+ci.guix.gnu.org should be backed by several head nodes.
+
+@item
+Improve backup: there's currently ad-hoc backup of selected pieces over rsync
+between the two head nodes; we can improve on that, for example with a
+dedicated backup site and proper testing of recoverability.
+
+@item
+Support mirroring: We'd like to make it easy for others to mirror substitutes
+from ci.guix and bordeaux.guix, perhaps by offering public rsync access.
+
+@item
+Optimize our web services: Monitor the performance of our services and tweak
+nginx config or whatever it takes to improve it.
+
+There is no time constraint on this activity: any improvement is welcome,
+whenever you can work on it.
+
+Prerequisite: Familiarity with Guix System administration and ideally with the
+infrastructure handbook:
+
+@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/infra-handbook.org}
+
+@end itemize
+
+@node Day-to-day system administration
+@subsection Day-to-day system administration
+
+We're also looking for people who'd be willing to have SSH access to some of
+the infrastructure to help with day-to-day maintenance: restarting a build,
+restarting the occasional service that has gone wild (that can happen),
+reconfiguring/upgrading a machine, rebooting, etc.
+
+This day-to-day activity requires you to be available some of the time (during
+office hours or not, during the week-end or not), whenever is convenient for
+you, so you can react to issues reported on IRC, on the mailing list, or
+elsewhere, and synchronize with other sysadmins.
+
+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}
+
+@node On-site intervention
+@subsection On-site intervention
+
+The first front-end is currently generously hosted by the Max Delbrück Center
+(MDC), a research institute in Berlin, Germany. Only authorized personnel can
+physically access it.
+
+The second one, bordeaux.guix.gnu.org, is hosted in Bordeaux, France, in a
+professional data center shared with non-profit ISP Aquilenet.  If you live in
+the region of Bordeaux and would like to help out when we need to go on-site,
+please make yourself known by emailing @email{guix-sysadmin@@gnu.org}.
+
+On-site interventions are rare, but they're usually in response to an
+emergency.
+
+@node Hosting
+@subsection Hosting
+
+We're looking for people who can host machines and help out whenever
+physical access is needed.  More specifically:
+
+@itemize
+@item
+We need hosting of “small” machines such as single-board computers (AArch64,
+RISC-V) for use as build machines.
+
+@item
+We need hosting for front-ends and x86_64 build machines in a data center where
+they can be racked and where, ideally, several local Guix sysadmins can
+physically access them.
+@end itemize
+
+The machines should be accessible over Wireguard VPN most of the
+time, so longer power or network interruptions should be the
+exception.
+
+Prerequisites: Familiarity with installing and remotely administering Guix
+System.
+
+@node Administrative tasks
+@subsection Administrative tasks
+
+The infra remains up and running thanks to crucial administrative tasks, which
+includes:
+
+@itemize
+@item
+Selecting and purchasing hardware, for example build machines.
+@item
+Renewing domain names.
+
+@item
+Securing funding, in particular via the Guix Foundation:
+@url{https://foundation.guix.info}
+@end itemize
+
+Prerequisites: Familiarity with hardware, and/or DNS registrars,
+and/or sponsorship, and/or crowdfunding.