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

[Ekaitz Zarraga <ekaitz@elenq.tech>]

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

Hi,

> 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”.

I just copied what you wrote :)

If it becomes outdated we could update... that's the good part of a 
living document. We have thousands of software packages in the same 
repository, that become outdated way faster than the documentation. I 
think we should encourage people to update documentation as we do with 
the packages. Still, I agree with what you say, it can be hard to keep 
up with translations.

We could evolve it to become more generic so it doesn't need that many 
updates, but still keep the essence that people should pay attention to 
the fact that we need help with the infrastructure.

>> +@node Contributing to Guix's infrastructure
>> +@section Contributing to Guix's infrastructure
> 
> Nitpick: Could you use title case for all section/node titles?

Ok

>> +@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}

Sure.

>> +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.

Ok

> Could you send an updated version?

Find it attached.

> Thanks!
> 
> Ludo’.

Thank you!


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

It depends on if we consider contributing is really part of how to use 
Guix or not. I'm ok with keeping it here but also with moving it 
somewhere else.

[-- Attachment #2: v3-0001-doc-Add-Contributing-to-Guix-s-infrastructure.patch --]
[-- Type: text/x-patch, Size: 8676 bytes --]

From a5c864482737af130afae42e32a51d316be61fb5 Mon Sep 17 00:00:00 2001
Message-ID: <a5c864482737af130afae42e32a51d316be61fb5.1732143300.git.ekaitz@elenq.tech>
From: Ekaitz Zarraga <ekaitz@elenq.tech>
Date: Thu, 7 Nov 2024 10:03:58 +0100
Subject: [PATCH v3] doc: Add "Contributing to Guix's infrastructure".
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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 | 193 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 193 insertions(+)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 8b9aa82bc8..cf5dfd7cfb 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -39,6 +39,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
@@ -3607,3 +3608,195 @@ 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, bffe}
+@item Cuirass: @url{https://guix.gnu.org/cuirass/, Cuirass}
+@item Goggles (IRC logger):
+@url{https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/hydra/goggles.scm,
+Goggles}
+@item Guix Build Coordinator:
+@url{https://git.savannah.gnu.org/cgit/guix/build-coordinator.git/,
+Build-Coordinator}
+@item Guix Data Service:
+@url{https://git.savannah.gnu.org/git/guix/data-service.git/, Data-Service}
+@item Guix Packages Website:
+@url{https://codeberg.org/luis-felipe/guix-packages-website.git,
+Guix-Packages-Website}
+@item mumi: @url{https://git.savannah.gnu.org/cgit/guix/mumi.git/, Mumi}
+@item nar-herder: @url{https://git.savannah.gnu.org/cgit/guix/nar-herder.git/,
+Nar-Herder}
+@item QA Frontpage:
+@url{https://git.savannah.gnu.org/git/guix/qa-frontpage.git, Qa-Frontpage}
+@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,
+Infra-Handbook}
+
+@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,
+Infra-Handbook}
+
+@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, Guix Foundation}
+@end itemize
+
+Prerequisites: Familiarity with hardware, and/or DNS registrars,
+and/or sponsorship, and/or crowdfunding.

base-commit: d108a7aac2c51f21c55cb8ea8801629a97f5242a
-- 
2.46.0