From b8baebae6a6188ed97048891f9ecb0b2f6a71085 Mon Sep 17 00:00:00 2001
From: Xinglu Chen <public@yoctocell.xyz>
Date: Sun, 6 Jun 2021 12:37:23 +0200
Subject: doc: Add reference for ‘git-version’ and ‘hg-version’.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* doc/contributing.texi (Version Numbers): Document ‘git-version’ and
  ‘hg-version’.
* doc/guix.texi (package Reference): Reference ‘Version Numbers’ section for
  version naming guidelines.

Signed-off-by: Ludovic Courtès <ludo@gnu.org>
---
 doc/contributing.texi | 22 +++++++++++++++++++---
 doc/guix.texi         |  4 +++-
 2 files changed, 22 insertions(+), 4 deletions(-)

(limited to 'doc')

diff --git a/doc/contributing.texi b/doc/contributing.texi
index fa8c0cf3ba..d67e632520 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -532,9 +532,11 @@ It is a good idea to strip commit identifiers in the @code{version}
 field to, say, 7 digits.  It avoids an aesthetic annoyance (assuming
 aesthetics have a role to play here) as well as problems related to OS
 limits such as the maximum shebang length (127 bytes for the Linux
-kernel).  It is best to use the full commit identifiers in
-@code{origin}s, though, to avoid ambiguities.  A typical package
-definition may look like this:
+kernel).  There are helper functions for doing this for packages using
+@code{git-fetch} or @code{hg-fetch} (see below).  It is best to use the
+full commit identifiers in @code{origin}s, though, to avoid ambiguities.
+A typical package definition may look like this:
+
 
 @lisp
 (define my-package
@@ -553,6 +555,20 @@ definition may look like this:
       )))
 @end lisp
 
+@deffn {Scheme Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT}
+Return the version string for packages using @code{git-fetch}.
+
+@lisp
+(git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05")
+@result{} "0.2.3-0.93818c9"
+@end lisp
+@end deffn
+
+@deffn {Scheme Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET}
+Return the version string for packages using @code{hg-fetch}.  It works
+in the same way as @code{git-version}.
+@end deffn
+
 @node Synopses and Descriptions
 @subsection Synopses and Descriptions
 
diff --git a/doc/guix.texi b/doc/guix.texi
index eb64518a95..e71ec70859 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -89,6 +89,7 @@ Copyright @copyright{} 2020 Jonathan Brielmaier@*
 Copyright @copyright{} 2020 Edgar Vincent@*
 Copyright @copyright{} 2021 Maxime Devos@*
 Copyright @copyright{} 2021 B. Wilson@*
+Copyright @copyright{} 2021 Xinglu Chen@*
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -6657,7 +6658,8 @@ This is the data type representing a package recipe.
 The name of the package, as a string.
 
 @item @code{version}
-The version of the package, as a string.
+The version of the package, as a string.  @xref{Version Numbers}, for
+guidelines.
 
 @item @code{source}
 An object telling how the source code for the package should be
-- 
cgit v1.2.3


From 6b752bd29a8d7adfb085e59efb170a27f8b805fd Mon Sep 17 00:00:00 2001
From: Ludovic Courtès <ludo@gnu.org>
Date: Tue, 8 Jun 2021 09:06:56 +0200
Subject: doc: Update minimum Guile-Git version.

* doc/guix.texi (Requirements): Update Guile-Git version.
---
 doc/guix.texi | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

(limited to 'doc')

diff --git a/doc/guix.texi b/doc/guix.texi
index e71ec70859..59b4ac11b4 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -856,9 +856,7 @@ version 0.1.0 or later;
 @item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
 @item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
 @item
-@c FIXME: We need the #:fetch-options parameter of 'submodule-update',
-@c which appeared in 0.5.0.  Change below after string freeze.
-@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.3.0
+@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0
 or later;
 @item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
 4.3.0 or later;
-- 
cgit v1.2.3


From 483f537081b9b5ccf026373d6743761aba6946e3 Mon Sep 17 00:00:00 2001
From: "Paul A. Patience" <paul@apatience.com>
Date: Sun, 6 Jun 2021 19:55:50 -0400
Subject: doc, gnu, guix: Fix typos.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* doc/guix.texi: Fix various typos and reword a sentence.
* gnu/packages/cpp.scm (cpplint)[description]: Fix typo.
* gnu/packages/dns.scm (ldns): Fix typo in comment.
* gnu/packages/games.scm (yamagi-quake2): Fix typo in comment.
* gnu/packages/qt.scm (python-pyqtwebengine): Fix typo in comment.
* gnu/packages/rails.scm (ruby-autoprefixer-rails): Fix typo in comment.
* gnu/packages/syndication.scm (quiterss)[description]: Fix typo.
* gnu/packages/terminals.scm (kmscon): Fix typo in comment.
* gnu/packages/xml.scm (perl-xml-sax-base)[description]: Fix typo.
  (python-elementpath)[description]: Fix typo.
* guix/build/asdf-build-system.scm (output-translation): Fix typo in docstring.

Signed-off-by: Ludovic Courtès <ludo@gnu.org>
---
 doc/guix.texi                    | 8 ++++----
 gnu/packages/cpp.scm             | 2 +-
 gnu/packages/dns.scm             | 2 +-
 gnu/packages/games.scm           | 2 +-
 gnu/packages/qt.scm              | 2 +-
 gnu/packages/rails.scm           | 4 ++--
 gnu/packages/syndication.scm     | 2 +-
 gnu/packages/terminals.scm       | 2 +-
 gnu/packages/xml.scm             | 4 ++--
 guix/build/asdf-build-system.scm | 3 +--
 10 files changed, 15 insertions(+), 16 deletions(-)

(limited to 'doc')

diff --git a/doc/guix.texi b/doc/guix.texi
index 59b4ac11b4..e7c783bd95 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -7807,7 +7807,7 @@ MbedTLS package:
 Some older packages that aren't using @file{Package.toml} yet, will require
 this file to be created, too.  The function @code{julia-create-package-toml}
 helps creating the file.  You need to pass the outputs and the source of the
-package, it's name (the same as the @code{file-name} parameter), the package
+package, its name (the same as the @code{file-name} parameter), the package
 uuid, the package version, and a list of dependencies specified by their name
 and their uuid.
 @end defvr
@@ -21755,7 +21755,7 @@ Available @code{getmail-options-configuration} fields are:
 If set to @samp{0}, getmail will only print warnings and errors.  A
 value of @samp{1} means that messages will be printed about retrieving
 and deleting messages.  If set to @samp{2}, getmail will print messages
-about each of it's actions.
+about each of its actions.
 
 Defaults to @samp{1}.
 
@@ -25502,7 +25502,7 @@ directives} for comprehensive documentation on the acceptable
 @deftp {Data type} php-fpm-dynamic-process-manager-configuration
 Data Type for the @code{dynamic} php-fpm process manager.  With the
 @code{dynamic} process manager, spare worker processes are kept around
-based on it's configured limits.
+based on its configured limits.
 @table @asis
 @item @code{max-children} (default: @code{5})
 Maximum of worker processes.
@@ -31570,7 +31570,7 @@ notifications.
 
 The kernel module loader service allows one to load loadable kernel
 modules at boot.  This is especially useful for modules that don't
-autoload and need to be manually loaded, as it's the case with
+autoload and need to be manually loaded, as is the case with
 @code{ddcci}.
 
 @deffn {Scheme Variable} kernel-module-loader-service-type
diff --git a/gnu/packages/cpp.scm b/gnu/packages/cpp.scm
index 3089094eb8..54f9da4b27 100644
--- a/gnu/packages/cpp.scm
+++ b/gnu/packages/cpp.scm
@@ -587,7 +587,7 @@ tools:
     (synopsis "Static code checker for C++")
     (description "@code{cpplint} is a command-line tool to check C/C++ files
 for style issues following Google’s C++ style guide.  While Google maintains
-it's own version of the tool, this is a fork that aims to be more responsive
+its own version of the tool, this is a fork that aims to be more responsive
 and make @code{cpplint} usable in wider contexts.")
     (license license:bsd-3)))
 
diff --git a/gnu/packages/dns.scm b/gnu/packages/dns.scm
index 641681320c..199b876369 100644
--- a/gnu/packages/dns.scm
+++ b/gnu/packages/dns.scm
@@ -101,7 +101,7 @@
         (base32 "0ac242n7996fswq1a3nlh1bbbhrsdwsq4mx7xq8ffq6aplb4rj4a"))
        (patches
         (search-patches
-         ;; To create make-flag vairables,
+         ;; To create make-flag variables,
          ;; for splitting installation of drill and examples.
          "ldns-drill-examples.patch"))))
     (build-system gnu-build-system)
diff --git a/gnu/packages/games.scm b/gnu/packages/games.scm
index 2eaea5868e..26d3567024 100644
--- a/gnu/packages/games.scm
+++ b/gnu/packages/games.scm
@@ -7151,7 +7151,7 @@ some graphical niceities, and numerous bug-fixes and other improvements.")
                (mkdir-p (string-append out "/lib"))
                (mkdir-p (string-append out "/bin"))
                ;; The yamagi-quake2 binary must be in the same directory
-               ;; as it's engine libraries, but symlinking it to /bin is okay
+               ;; as its engine libraries, but symlinking it to /bin is okay.
                ;; https://github.com/yquake2/yquake2/blob/master/stuff/packaging.md
                (copy-recursively "release"
                                  (string-append out "/lib/yamagi-quake2"))
diff --git a/gnu/packages/qt.scm b/gnu/packages/qt.scm
index 6bb1281570..f992314777 100644
--- a/gnu/packages/qt.scm
+++ b/gnu/packages/qt.scm
@@ -2068,7 +2068,7 @@ contain over 620 classes.")
                        "--sipdir" sipdir
                        "--pyqt-sipdir" pyqt-sipdir))))
          ;; Because this has a different prefix than python-pyqt then we need
-         ;; to make this a namespace of it's own
+         ;; to make this a namespace of its own.
          (add-after 'install 'make-namespace
            (lambda* (#:key inputs outputs #:allow-other-keys)
              (let* ((__init__.py (string-append
diff --git a/gnu/packages/rails.scm b/gnu/packages/rails.scm
index e9c390a1a0..76ed4df6e4 100644
--- a/gnu/packages/rails.scm
+++ b/gnu/packages/rails.scm
@@ -142,8 +142,8 @@ API.")
        (modify-phases %standard-phases
          (add-after 'extract-gemspec 'remove-unnecessary-dependencies
            (lambda _
-             ;; Remove the testing of compass, as it's use is deprecated, and
-             ;; it's unpackaged for Guix
+             ;; Remove the testing of compass, as its use is deprecated, and
+             ;; it's unpackaged for Guix.
              (substitute* "autoprefixer-rails.gemspec"
                ((".*%q<compass>.*") "\n")
                (("\"spec/compass_spec\\.rb\"\\.freeze, ") ""))
diff --git a/gnu/packages/syndication.scm b/gnu/packages/syndication.scm
index fc4efb24f6..9d4325ffdf 100644
--- a/gnu/packages/syndication.scm
+++ b/gnu/packages/syndication.scm
@@ -576,7 +576,7 @@ formats, including all versions of RSS and Atom.")
     (home-page "https://quiterss.org/")
     (synopsis "RSS/Atom news feeds reader written on Qt/C++")
     (description "QuiteRSS is an RSS/Atom news feeds reader written on Qt/C++
-that aims to be quite fast and comfortable to it's user.")
+that aims to be quite fast and comfortable to its user.")
     (license license:gpl3+)))
 
 (define-public gfeeds
diff --git a/gnu/packages/terminals.scm b/gnu/packages/terminals.scm
index 37636c7cdc..06ace5e238 100644
--- a/gnu/packages/terminals.scm
+++ b/gnu/packages/terminals.scm
@@ -326,7 +326,7 @@ compatibility to existing emulators like xterm, gnome-terminal, konsole, etc.")
          ("libxkbcommon" ,libxkbcommon)
          ("logind" ,elogind)
          ;; MESA can be used for accelerated video output via OpenGLESv2, but
-         ;; it's a bit dependency that we'd rather avoid in the installation
+         ;; it's a big dependency that we'd rather avoid in the installation
          ;; image.
          ;; ("mesa" ,mesa)
          ("pango" ,pango)
diff --git a/gnu/packages/xml.scm b/gnu/packages/xml.scm
index 9ddd02a613..e2d5ca8176 100644
--- a/gnu/packages/xml.scm
+++ b/gnu/packages/xml.scm
@@ -878,7 +878,7 @@ building Perl SAX2 XML parsers, filters, and drivers.")
     (home-page "https://metacpan.org/release/XML-SAX-Base")
     (synopsis "Base class for SAX Drivers and Filters")
     (description "This module has a very simple task - to be a base class for
-PerlSAX drivers and filters.  It's default behaviour is to pass the input
+PerlSAX drivers and filters.  Its default behaviour is to pass the input
 directly to the output unchanged.  It can be useful to use this module as a
 base class so you don't have to, for example, implement the characters()
 callback.")
@@ -2587,7 +2587,7 @@ for Python's ElementTree XML data structures, both for the standard
 ElementTree library and for the @uref{http://lxml.de, lxml.etree} library.
 
 For lxml.etree this package can be useful for providing XPath 2.0 selectors,
-because lxml.etree already has it's own implementation of XPath 1.0.")
+because lxml.etree already has its own implementation of XPath 1.0.")
     (license license:expat)))
 
 (define-public python-lxml
diff --git a/guix/build/asdf-build-system.scm b/guix/build/asdf-build-system.scm
index 7f1037c4f9..6186613e52 100644
--- a/guix/build/asdf-build-system.scm
+++ b/guix/build/asdf-build-system.scm
@@ -72,8 +72,7 @@
 
 (define (output-translation source-path
                             object-output)
-  "Return a translation for the system's source path
-to it's binary output."
+  "Return a translation for the system's source path to its binary output."
   `((,source-path
      :**/ :*.*.*)
     (,(library-directory object-output)
-- 
cgit v1.2.3


From 0b5120fb03db5226871b3482a72b1e6fdaa59ead Mon Sep 17 00:00:00 2001
From: Luis Felipe <luis.felipe.la@protonmail.com>
Date: Mon, 1 Mar 2021 11:15:16 -0500
Subject: doc: Fix reference to the bind package variable name.

* doc/guix.texi (Globally-Visible Packages): Change "bind" variable
name to the actual variable name, "isc-bind".

Signed-off-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
---
 doc/guix.texi | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc')

diff --git a/doc/guix.texi b/doc/guix.texi
index e7c783bd95..cc5ca18256 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -13455,12 +13455,12 @@ of a package:
 
 (operating-system
   ;; ...
-  (packages (cons (list bind "utils")
+  (packages (cons (list isc-bind "utils")
                   %base-packages)))
 @end lisp
 
 @findex specification->package
-Referring to packages by variable name, like @code{bind} above, has
+Referring to packages by variable name, like @code{isc-bind} above, has
 the advantage of being unambiguous; it also allows typos and such to be
 diagnosed right away as ``unbound variables''.  The downside is that one
 needs to know which module defines which package, and to augment the
-- 
cgit v1.2.3


From 571dc36a69448192a0d76c85091cf76c53739811 Mon Sep 17 00:00:00 2001
From: Tobias Geerinckx-Rice <me@tobias.gr>
Date: Thu, 17 Jun 2021 11:18:01 +0200
Subject: doc: Update QEMU command line.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* doc/guix.texi (Invoking guix system): Substitute ‘-nic’ for the
obsolete ‘-net’.
---
 doc/guix.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/guix.texi b/doc/guix.texi
index cc5ca18256..0930a514c7 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -33225,7 +33225,7 @@ below, which enables networking and requests 1@tie{}GiB of RAM for the
 emulated machine:
 
 @example
-$ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -net user,model=virtio-net-pci
+$ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -nic user,model=virtio-net-pci
 @end example
 
 The VM shares its store with the host system.
-- 
cgit v1.2.3


From 4985a4272497bf9ba87a2190353d915da9b55906 Mon Sep 17 00:00:00 2001
From: Christopher Baines <mail@cbaines.net>
Date: Sat, 15 May 2021 11:02:36 +0100
Subject: Start enabling substitutes from bordeaux.guix.gnu.org.

In addition to substitutes from ci.guix.gnu.org.  There are more changes that
can be made in the future, but these changes seem like a good start.

* config-daemon.ac (guix_substitute_urls): Add https://bordeaux.guix.gnu.org.
* guix/scripts/substitute.scm (%default-substitute-urls): Add
http://bordeaux.guix.gnu.org.
* guix/store.scm (%default-substitute-urls): Add bordeaux.guix.gnu.org.
* doc/guix.texi: Adjust accordingly.
* doc/contributing.texi: Adjust accordingly.
---
 config-daemon.ac            |   2 +-
 doc/contributing.texi       |   8 +--
 doc/guix.texi               | 142 ++++++++++++++++++++++++--------------------
 guix/scripts/substitute.scm |   3 +-
 guix/store.scm              |   3 +-
 5 files changed, 86 insertions(+), 72 deletions(-)

(limited to 'doc')

diff --git a/config-daemon.ac b/config-daemon.ac
index 85caee269b..5ddc740600 100644
--- a/config-daemon.ac
+++ b/config-daemon.ac
@@ -117,7 +117,7 @@ if test "x$guix_build_daemon" = "xyes"; then
 
   dnl Determine the appropriate default list of substitute URLs (GnuTLS
   dnl is required so we can default to 'https'.)
-  guix_substitute_urls="https://ci.guix.gnu.org"
+  guix_substitute_urls="https://ci.guix.gnu.org https://bordeaux.guix.gnu.org"
 
   AC_MSG_CHECKING([for default substitute URLs])
   AC_MSG_RESULT([$guix_substitute_urls])
diff --git a/doc/contributing.texi b/doc/contributing.texi
index d67e632520..1086bb9fd4 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -376,12 +376,12 @@ Once your package builds correctly, please send us a patch
 (@pxref{Submitting Patches}).  Well, if you need help, we will be happy to
 help you too.  Once the patch is committed in the Guix repository, the
 new package automatically gets built on the supported platforms by
-@url{@value{SUBSTITUTE-URL}, our continuous integration system}.
+@url{https://@value{SUBSTITUTE-SERVER-1}, our continuous integration system}.
 
 @cindex substituter
 Users can obtain the new package definition simply by running
 @command{guix pull} (@pxref{Invoking guix pull}).  When
-@code{@value{SUBSTITUTE-SERVER}} is done building the package, installing the
+@code{@value{SUBSTITUTE-SERVER-1}} is done building the package, installing the
 package automatically downloads binaries from there
 (@pxref{Substitutes}).  The only place where human intervention is
 needed is to review and apply the patch.
@@ -1107,7 +1107,7 @@ changes).  This branch is intended to be merged in @code{master} every
 until late in its development process.
 @end table
 
-All these branches are @uref{@value{SUBSTITUTE-URL},
+All these branches are @uref{https://@value{SUBSTITUTE-SERVER-1},
 tracked by our build farm} and merged into @code{master} once
 everything has been successfully built.  This allows us to fix issues
 before they hit users, and to reduce the window during which pre-built
@@ -1141,7 +1141,7 @@ as timestamps or randomly-generated output in the build result.
 
 Another option is to use @command{guix challenge} (@pxref{Invoking guix
 challenge}).  You may run it once the package has been committed and
-built by @code{@value{SUBSTITUTE-SERVER}} to check whether it obtains the same
+built by @code{@value{SUBSTITUTE-SERVER-1}} to check whether it obtains the same
 result as you did.  Better yet: Find another machine that can build it
 and run @command{guix publish}.  Since the remote build machine is
 likely different from yours, this can catch non-determinism issues
diff --git a/doc/guix.texi b/doc/guix.texi
index 0930a514c7..094d1acd2c 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -17,8 +17,9 @@
 @set BASE-URL https://ftp.gnu.org/gnu/guix
 
 @c The official substitute server used by default.
-@set SUBSTITUTE-SERVER ci.guix.gnu.org
-@set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER}
+@set SUBSTITUTE-SERVER-1 ci.guix.gnu.org
+@set SUBSTITUTE-SERVER-2 bordeaux.guix.gnu.org
+@set SUBSTITUTE-URLS https://@value{SUBSTITUTE-SERVER-1} https://@value{SUBSTITUTE-SERVER-2}
 
 @copying
 Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ludovic Courtès@*
@@ -229,7 +230,7 @@ Package Management
 
 Substitutes
 
-* Official Substitute Server::  One particular source of substitutes.
+* Official Substitute Servers::  One particular source of substitutes.
 * Substitute Server Authorization::  How to enable or disable substitutes.
 * Getting Substitutes from Other Servers::  Substitute diversity.
 * Substitute Authentication::   How Guix verifies substitutes.
@@ -780,12 +781,15 @@ Info search path).
 
 @item
 @cindex substitutes, authorization thereof
-To use substitutes from @code{@value{SUBSTITUTE-SERVER}} or one of its mirrors
-(@pxref{Substitutes}), authorize them:
+To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}},
+@code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}),
+authorize them:
 
 @example
 # guix archive --authorize < \
-     ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.pub
+     ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
+# guix archive --authorize < \
+     ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
 @end example
 
 @quotation Note
@@ -1547,7 +1551,7 @@ remote procedure call (@pxref{The Store}).
 @item --substitute-urls=@var{urls}
 Consider @var{urls} the default whitespace-separated list of substitute
 source URLs.  When this option is omitted,
-@indicateurl{https://@value{SUBSTITUTE-SERVER}} is used.
+@indicateurl{@value{SUBSTITUTE-URLS}} is used.
 
 This means that substitutes may be downloaded from @var{urls}, as long
 as they are signed by a trusted signature (@pxref{Substitutes}).
@@ -3685,7 +3689,7 @@ pre-built package binaries, but source tarballs, for instance, which
 also result from derivation builds, can be available as substitutes.
 
 @menu
-* Official Substitute Server::  One particular source of substitutes.
+* Official Substitute Servers::  One particular source of substitutes.
 * Substitute Server Authorization::  How to enable or disable substitutes.
 * Getting Substitutes from Other Servers::  Substitute diversity.
 * Substitute Authentication::   How Guix verifies substitutes.
@@ -3694,14 +3698,15 @@ also result from derivation builds, can be available as substitutes.
 * On Trusting Binaries::        How can you trust that binary blob?
 @end menu
 
-@node Official Substitute Server
-@subsection Official Substitute Server
+@node Official Substitute Servers
+@subsection Official Substitute Servers
 
 @cindex build farm
-The @code{@value{SUBSTITUTE-SERVER}} server is a front-end to an official build farm
-that builds packages from Guix continuously for some
-architectures, and makes them available as substitutes.  This is the
-default source of substitutes; it can be overridden by passing the
+@code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}} are both front-ends to official build
+farms that build packages from Guix continuously for some architectures,
+and make them available as substitutes.  These are the default source of
+substitutes; which can be overridden by passing the
 @option{--substitute-urls} option either to @command{guix-daemon}
 (@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
 or to client tools such as @command{guix package}
@@ -3714,7 +3719,7 @@ using HTTP makes all communications visible to an eavesdropper, who
 could use the information gathered to determine, for instance, whether
 your system has unpatched security vulnerabilities.
 
-Substitutes from the official build farm are enabled by default when
+Substitutes from the official build farms are enabled by default when
 using Guix System (@pxref{GNU Distribution}).  However,
 they are disabled by default when using Guix on a foreign distribution,
 unless you have explicitly enabled them via one of the recommended
@@ -3730,27 +3735,28 @@ other substitute server.
 @cindex substitutes, authorization thereof
 @cindex access control list (ACL), for substitutes
 @cindex ACL (access control list), for substitutes
-To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER}} or a
-mirror thereof, you
-must add its public key to the access control list (ACL) of archive
+To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER-1}}, @code{@value{SUBSTITUTE-SERVER-2}} or a mirror, you
+must add the releavnt public key to the access control list (ACL) of archive
 imports, using the @command{guix archive} command (@pxref{Invoking guix
-archive}).  Doing so implies that you trust @code{@value{SUBSTITUTE-SERVER}} to not
+archive}).  Doing so implies that you trust the substitute server to not
 be compromised and to serve genuine substitutes.
 
 @quotation Note
 If you are using Guix System, you can skip this section: Guix System
-authorizes substitutes from @code{@value{SUBSTITUTE-SERVER}} by default.
+authorizes substitutes from @code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}} by default.
 @end quotation
 
-The public key for @code{@value{SUBSTITUTE-SERVER}} is installed along with Guix, in
-@code{@var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, where @var{prefix} is
-the installation prefix of Guix.  If you installed Guix from source,
-make sure you checked the GPG signature of
+The public keys for each of the project maintained substitute servers
+are installed along with Guix, in @code{@var{prefix}/share/guix/}, where
+@var{prefix} is the installation prefix of Guix.  If you installed Guix
+from source, make sure you checked the GPG signature of
 @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
 Then, you can run something like this:
 
 @example
-# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub
+# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
+# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
 @end example
 
 Once this is in place, the output of a command like @code{guix build}
@@ -3782,8 +3788,8 @@ $ guix build emacs --dry-run
 @noindent
 The text changed from ``The following derivations would be built'' to
 ``112.3 MB would be downloaded''.  This indicates that substitutes from
-@code{@value{SUBSTITUTE-SERVER}} are usable and will be downloaded, when
-possible, for future builds.
+the configured substitute servers are usable and will be downloaded,
+when possible, for future builds.
 
 @cindex substitutes, how to disable
 The substitute mechanism can be disabled globally by running
@@ -3817,8 +3823,9 @@ its configuration and add the URLs and substitute keys that you want
 
 As an example, suppose you want to fetch substitutes from
 @code{guix.example.org} and to authorize the signing key of that server,
-in addition to the default @code{@value{SUBSTITUTE-SERVER}}.  The
-resulting operating system configuration will look something like:
+in addition to the default @code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}}.  The resulting operating system
+configuration will look something like:
 
 @lisp
 (operating-system
@@ -3862,7 +3869,7 @@ line and list the URLs of interest (@pxref{daemon-substitute-urls,
 @code{guix-daemon --substitute-urls}}):
 
 @example
-@dots{} --substitute-urls='https://guix.example.org https://@value{SUBSTITUTE-SERVER}'
+@dots{} --substitute-urls='https://guix.example.org @value{SUBSTITUTE-URLS}'
 @end example
 
 @item
@@ -3885,10 +3892,12 @@ Again this assumes @file{key.pub} contains the public key that
 @end enumerate
 
 Now you're all set!  Substitutes will be preferably taken from
-@code{https://guix.example.org}, using @code{@value{SUBSTITUTE-SERVER}}
-as a fallback.  Of course you can list as many substitute servers as you
-like, with the caveat that substitute lookup can be slowed down if too
-many servers need to be contacted.
+@code{https://guix.example.org}, using
+@code{@value{SUBSTITUTE-SERVER-1}} then
+@code{@value{SUBSTITUTE-SERVER-2}} as fallback options.  Of course you
+can list as many substitute servers as you like, with the caveat that
+substitute lookup can be slowed down if too many servers need to be
+contacted.
 
 Note that there are also situations where one may want to add the URL of
 a substitute server @emph{without} authorizing its key.
@@ -3976,12 +3985,12 @@ by a server.
 Today, each individual's control over their own computing is at the
 mercy of institutions, corporations, and groups with enough power and
 determination to subvert the computing infrastructure and exploit its
-weaknesses.  While using @code{@value{SUBSTITUTE-SERVER}} substitutes can be
-convenient, we encourage users to also build on their own, or even run
-their own build farm, such that @code{@value{SUBSTITUTE-SERVER}} is less of an
-interesting target.  One way to help is by publishing the software you
-build using @command{guix publish} so that others have one more choice
-of server to download substitutes from (@pxref{Invoking guix publish}).
+weaknesses.  While using substitutes can be convenient, we encourage
+users to also build on their own, or even run their own build farm, such
+that the project run substitute servers are less of an interesting
+target.  One way to help is by publishing the software you build using
+@command{guix publish} so that others have one more choice of server to
+download substitutes from (@pxref{Invoking guix publish}).
 
 Guix has the foundations to maximize build reproducibility
 (@pxref{Features}).  In most cases, independent builds of a given
@@ -4945,11 +4954,11 @@ Read a single-item archive as served by substitute servers
 low-level operation needed in only very narrow use cases; see below.
 
 For example, the following command extracts the substitute for Emacs
-served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}:
+served by @code{@value{SUBSTITUTE-SERVER-1}} to @file{/tmp/emacs}:
 
 @example
 $ wget -O - \
-  https://@value{SUBSTITUTE-SERVER}/nar/gzip/@dots{}-emacs-24.5 \
+  https://@value{SUBSTITUTE-SERVER-1}/nar/gzip/@dots{}-emacs-24.5 \
   | gunzip | guix archive -x /tmp/emacs
 @end example
 
@@ -4971,7 +4980,7 @@ this example:
 
 @example
 $ wget -O - \
-  https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-emacs-26.3 \
+  https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-emacs-26.3 \
   | lzip -d | guix archive -t
 @end example
 
@@ -10905,7 +10914,7 @@ but you are actually on an @code{x86_64} machine:
 
 @example
 $ guix build --log-file gdb -s aarch64-linux
-https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10
+https://@value{SUBSTITUTE-SERVER-1}/log/@dots{}-gdb-7.10
 @end example
 
 You can freely access a huge library of build logs!
@@ -12558,7 +12567,7 @@ When @command{guix publish} runs, it spawns an HTTP server which allows
 anyone with network access to obtain substitutes from it.  This means
 that any machine running Guix can also act as if it were a build farm,
 since the HTTP interface is compatible with Cuirass, the software behind
-the @code{@value{SUBSTITUTE-SERVER}} build farm.
+the @code{@value{SUBSTITUTE-SERVER-1}} build farm.
 
 For security, each substitute is signed, allowing recipients to check
 their authenticity and integrity (@pxref{Substitutes}).  Because
@@ -12847,12 +12856,12 @@ any given store item.
 The command output looks like this:
 
 @smallexample
-$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org"
-updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER}'... 100.0%
+$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
+updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
 updating list of substitutes from 'https://guix.example.org'... 100.0%
 /gnu/store/@dots{}-openssl-1.0.2d contents differ:
   local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
-  https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
+  https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
   https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
   differing files:
     /lib/libcrypto.so.1.1
@@ -12860,14 +12869,14 @@ updating list of substitutes from 'https://guix.example.org'... 100.0%
 
 /gnu/store/@dots{}-git-2.5.0 contents differ:
   local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
-  https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
+  https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
   https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
   differing file:
     /libexec/git-core/git-fsck
 
 /gnu/store/@dots{}-pius-2.1.1 contents differ:
   local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
-  https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
+  https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
   https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
   differing file:
     /share/man/man1/pius.1.gz
@@ -12889,7 +12898,7 @@ the servers obtained a result different from the local build.
 
 @cindex non-determinism, in package builds
 As an example, @code{guix.example.org} always gets a different answer.
-Conversely, @code{@value{SUBSTITUTE-SERVER}} agrees with local builds, except in the
+Conversely, @code{@value{SUBSTITUTE-SERVER-1}} agrees with local builds, except in the
 case of Git.  This might indicate that the build process of Git is
 non-deterministic, meaning that its output varies as a function of
 various things that Guix does not fully control, in spite of building
@@ -12905,7 +12914,7 @@ to run:
 @example
 guix challenge git \
   --diff=diffoscope \
-  --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org"
+  --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
 @end example
 
 This automatically invokes @command{diffoscope}, which displays detailed
@@ -12915,14 +12924,14 @@ Alternatively, we can do something along these lines (@pxref{Invoking guix
 archive}):
 
 @example
-$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-git-2.5.0 \
+$ wget -q -O - https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-git-2.5.0 \
    | lzip -d | guix archive -x /tmp/git
 $ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
 @end example
 
 This command shows the difference between the files resulting from the
 local build, and the files resulting from the build on
-@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging Files,,
+@code{@value{SUBSTITUTE-SERVER-1}} (@pxref{Overview, Comparing and Merging Files,,
 diffutils, Comparing and Merging Files}).  The @command{diff} command
 works great for text files.  When binary files differ, a better option
 is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
@@ -12937,7 +12946,7 @@ In the meantime, @command{guix challenge} is one tool to help address
 the problem.
 
 If you are writing packages for Guix, you are encouraged to check
-whether @code{@value{SUBSTITUTE-SERVER}} and other substitute servers obtain the
+whether @code{@value{SUBSTITUTE-SERVER-1}} and other substitute servers obtain the
 same build result as you did with:
 
 @example
@@ -13218,14 +13227,14 @@ on @var{a} and @var{a} has no substitutes, only @var{a} is listed, even though
 @var{b} usually lacks substitutes as well.  The result looks like this:
 
 @example
-$ guix weather --substitute-urls=@value{SUBSTITUTE-URL} -c 10
+$ guix weather --substitute-urls=@value{SUBSTITUTE-URLS} -c 10
 computing 8,983 package derivations for x86_64-linux...
-looking for 9,343 store items on @value{SUBSTITUTE-URL}...
-updating substitutes from '@value{SUBSTITUTE-URL}'... 100.0%
-@value{SUBSTITUTE-URL}
+looking for 9,343 store items on @value{SUBSTITUTE-URLS}...
+updating substitutes from '@value{SUBSTITUTE-URLS}'... 100.0%
+@value{SUBSTITUTE-URLS}
   64.7% substitutes available (6,047 out of 9,343)
 @dots{}
-2502 packages are missing from '@value{SUBSTITUTE-URL}' for 'x86_64-linux', among which:
+2502 packages are missing from '@value{SUBSTITUTE-URLS}' for 'x86_64-linux', among which:
     58  kcoreaddons@@5.49.0      /gnu/store/@dots{}-kcoreaddons-5.49.0
     46  qgpgme@@1.11.1           /gnu/store/@dots{}-qgpgme-1.11.1
     37  perl-http-cookiejar@@0.008  /gnu/store/@dots{}-perl-http-cookiejar-0.008
@@ -13234,7 +13243,7 @@ updating substitutes from '@value{SUBSTITUTE-URL}'... 100.0%
 
 What this example shows is that @code{kcoreaddons} and presumably the 58
 packages that depend on it have no substitutes at
-@code{@value{SUBSTITUTE-SERVER}}; likewise for @code{qgpgme} and the 46
+@code{@value{SUBSTITUTE-SERVER-1}}; likewise for @code{qgpgme} and the 46
 packages that depend on it.
 
 If you are a Guix developer, or if you are taking care of this build farm,
@@ -15441,7 +15450,9 @@ Number of build user accounts to create.
 @item @code{authorize-key?} (default: @code{#t})
 @cindex substitutes, authorization thereof
 Whether to authorize the substitute keys listed in
-@code{authorized-keys}---by default that of @code{@value{SUBSTITUTE-SERVER}}
+@code{authorized-keys}---by default that of
+@code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}}
 (@pxref{Substitutes}).
 
 When @code{authorize-key?} is true, @file{/etc/guix/acl} cannot be
@@ -15462,8 +15473,9 @@ allowed for in-place modifications to @file{/etc/guix/acl}.
 @item @code{authorized-keys} (default: @code{%default-authorized-guix-keys})
 The list of authorized key files for archive imports, as a list of
 string-valued gexps (@pxref{Invoking guix archive}).  By default, it
-contains that of @code{@value{SUBSTITUTE-SERVER}} (@pxref{Substitutes}).
-See @code{substitute-urls} below for an example on how to change it.
+contains that of @code{@value{SUBSTITUTE-SERVER-1}} and
+@code{@value{SUBSTITUTE-SERVER-2}} (@pxref{Substitutes}).  See
+@code{substitute-urls} below for an example on how to change it.
 
 @item @code{use-substitutes?} (default: @code{#t})
 Whether to use substitutes.
@@ -15472,7 +15484,7 @@ Whether to use substitutes.
 The list of URLs where to look for substitutes by default.
 
 Suppose you would like to fetch substitutes from @code{guix.example.org}
-in addition to @code{@value{SUBSTITUTE-SERVER}}.  You will need to do
+in addition to @code{@value{SUBSTITUTE-SERVER-1}}.  You will need to do
 two things: (1) add @code{guix.example.org} to @code{substitute-urls},
 and (2) authorize its signing key, having done appropriate checks
 (@pxref{Substitute Server Authorization}).  The configuration below does
diff --git a/guix/scripts/substitute.scm b/guix/scripts/substitute.scm
index 44448ff3e9..3ea1c73e10 100755
--- a/guix/scripts/substitute.scm
+++ b/guix/scripts/substitute.scm
@@ -643,7 +643,8 @@ found."
     (#f
      ;; This can only happen when this script is not invoked by the
      ;; daemon.
-     '("http://ci.guix.gnu.org"))))
+     '("http://ci.guix.gnu.org"
+       "http://bordeaux.guix.gnu.org"))))
 
 ;; In order to prevent using large number of discovered local substitute
 ;; servers, limit the local substitute urls list size.
diff --git a/guix/store.scm b/guix/store.scm
index b761264ac0..1ab2b08b47 100644
--- a/guix/store.scm
+++ b/guix/store.scm
@@ -787,7 +787,8 @@ encoding conversion errors."
   (map (if (false-if-exception (resolve-interface '(gnutls)))
            (cut string-append "https://" <>)
            (cut string-append "http://" <>))
-       '("ci.guix.gnu.org")))
+       '("ci.guix.gnu.org"
+         "bordeaux.guix.gnu.org")))
 
 (define (current-user-name)
   "Return the name of the calling user."
-- 
cgit v1.2.3


From aaf4a0090f9cd5e5fcc3f30e4ec45bf1b0c7b788 Mon Sep 17 00:00:00 2001
From: Ludovic Courtès <ludo@gnu.org>
Date: Mon, 24 May 2021 11:57:21 +0200
Subject: doc: Structure the "Commit Access" section.

* doc/contributing.texi (Commit Access): Add introduction and section
heading.  Separate OpenPGP setup from commit policy.
---
 doc/contributing.texi | 57 +++++++++++++++++++++++++++++++++------------------
 1 file changed, 37 insertions(+), 20 deletions(-)

(limited to 'doc')

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 1086bb9fd4..228ca63cfb 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1275,8 +1275,19 @@ this nifty tool!
 @section Commit Access
 
 @cindex commit access, for developers
-For frequent contributors, having write access to the repository is
-convenient.  When you deem it necessary, consider applying for commit
+Everyone can contribute to Guix without having commit access
+(@pxref{Submitting Patches}).  However, for frequent contributors,
+having write access to the repository can be convenient.  Commit access
+should not be thought of as a ``badge of honor'' but rather as a
+responsibility a contributor is willing to take to help the project.
+
+The following sections explain how to get commit access, how to be ready
+to push commits, and the policies and community expectations for commits
+pushed upstream.
+
+@subsection Applying for Commit Access
+
+When you deem it necessary, consider applying for commit
 access by following these steps:
 
 @enumerate
@@ -1348,24 +1359,6 @@ review and merging system, which, as a consequence, may lead us to have
 fewer people with commit access to the main repository.  Stay tuned!
 @end quotation
 
-If you get commit access, please make sure to follow
-the policy below (discussions of the policy can take place on
-@email{guix-devel@@gnu.org}).
-
-Non-trivial patches should always be posted to
-@email{guix-patches@@gnu.org} (trivial patches include fixing typos,
-etc.).  This mailing list fills the patch-tracking database
-(@pxref{Tracking Bugs and Patches}).
-
-For patches that just add a new package, and a simple one, it's OK to
-commit, if you're confident (which means you successfully built it in a
-chroot setup, and have done a reasonable copyright and license
-auditing).  Likewise for package upgrades, except upgrades that trigger
-a lot of rebuilds (for example, upgrading GnuTLS or GLib).  We have a
-mailing list for commit notifications (@email{guix-commits@@gnu.org}),
-so people can notice.  Before pushing your changes, make sure to run
-@code{git pull --rebase}.
-
 All commits that are pushed to the central repository on Savannah must
 be signed with an OpenPGP key, and the public key should be uploaded to
 your user account on Savannah and to public key servers, such as
@@ -1385,6 +1378,26 @@ Savannah by using the pre-push Git hook called located at
 cp etc/git/pre-push .git/hooks/pre-push
 @end example
 
+@subsection Commit Policy
+
+If you get commit access, please make sure to follow
+the policy below (discussions of the policy can take place on
+@email{guix-devel@@gnu.org}).
+
+Non-trivial patches should always be posted to
+@email{guix-patches@@gnu.org} (trivial patches include fixing typos,
+etc.).  This mailing list fills the patch-tracking database
+(@pxref{Tracking Bugs and Patches}).
+
+For patches that just add a new package, and a simple one, it's OK to
+commit, if you're confident (which means you successfully built it in a
+chroot setup, and have done a reasonable copyright and license
+auditing).  Likewise for package upgrades, except upgrades that trigger
+a lot of rebuilds (for example, upgrading GnuTLS or GLib).  We have a
+mailing list for commit notifications (@email{guix-commits@@gnu.org}),
+so people can notice.  Before pushing your changes, make sure to run
+@code{git pull --rebase}.
+
 When pushing a commit on behalf of somebody else, please add a
 @code{Signed-off-by} line at the end of the commit log message---e.g.,
 with @command{git am --signoff}.  This improves tracking of who did
@@ -1406,12 +1419,16 @@ you're confident, it's OK to commit.
 That last part is subject to being adjusted, allowing individuals to commit
 directly on non-controversial changes on parts they’re familiar with.
 
+@subsection Commit Revocation
+
 In order to reduce the possibility of mistakes, committers will have
 their Savannah account removed from the Guix Savannah project and their
 key removed from @file{.guix-authorizations} after 12 months of
 inactivity; they can ask to regain commit access by emailing the
 maintainers, without going through the vouching process.
 
+@subsection Helping Out
+
 One last thing: the project keeps moving forward because committers not
 only push their own awesome changes, but also offer some of their time
 @emph{reviewing} and pushing other people's changes.  As a committer,
-- 
cgit v1.2.3


From d4751342454a82a4c71c49733f4c5cd221f95b09 Mon Sep 17 00:00:00 2001
From: Ludovic Courtès <ludo@gnu.org>
Date: Mon, 24 May 2021 22:16:23 +0200
Subject: doc: Add "Addressing Issues" section.

* doc/contributing.texi (Addressing Issues): New section.

Co-authored-by: Christopher Baines <mail@cbaines.net>
---
 doc/contributing.texi | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

(limited to 'doc')

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 228ca63cfb..c0e60b63a4 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1419,6 +1419,45 @@ you're confident, it's OK to commit.
 That last part is subject to being adjusted, allowing individuals to commit
 directly on non-controversial changes on parts they’re familiar with.
 
+@subsection Addressing Issues
+
+Peer review (@pxref{Submitting Patches}) and tools such as
+@command{guix lint} (@pxref{Invoking guix lint}) and the test suite
+(@pxref{Running the Test Suite}) should catch issues before they are
+pushed.  Yet, commits that ``break'' functionality might occasionally
+go through.  When that happens, there are two priorities: mitigating
+the impact, and understanding what happened to reduce the chance of
+similar incidents in the future.  The responsibility for both these
+things primarily lies with those involved, but like everything this is
+a group effort.
+
+Some issues can directly affect all users---for instance because they
+make @command{guix pull} fail or break core functionality, because they
+break major packages (at build time or run time), or because they
+introduce known security vulnerabilities.
+
+@cindex reverting commits
+The people involved in authoring, reviewing, and pushing such
+commit(s) should be at the forefront to mitigate their impact in a
+timely fashion: by pushing a followup commit to fix it (if possible),
+or by reverting it to leave time to come up with a proper fix, and by
+communicating with other developers about the problem.
+
+If these persons are unavailable to address the issue in time, other
+committers are entitled to revert the commit(s), explaining in the
+commit log and on the mailing list what the problem was, with the goal
+of leaving time to the original committer, reviewer(s), and author(s)
+to propose a way forward.
+
+Once the problem has been dealt with, it is the responsibility of
+those involved to make sure the situation is understood.  If you are
+working to understand what happened, focus on gathering information
+and avoid assigning any blame.  Do ask those involved to describe what
+happened, do not ask them to explain the situation---this would
+implicitly blame them, which is unhelpful.  Accountability comes from
+a consensus about the problem, learning from it and improving
+processes so that it's less likely to reoccur.
+
 @subsection Commit Revocation
 
 In order to reduce the possibility of mistakes, committers will have
-- 
cgit v1.2.3


From d3d6d1c6eb61d008d042995500344ab8587d9d53 Mon Sep 17 00:00:00 2001
From: Ludovic Courtès <ludo@gnu.org>
Date: Mon, 24 May 2021 22:38:18 +0200
Subject: doc: Explain more reasons for commit revocation.

* doc/contributing.texi (Commit Revocation): Expound.
---
 doc/contributing.texi | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

(limited to 'doc')

diff --git a/doc/contributing.texi b/doc/contributing.texi
index c0e60b63a4..9e574f8b5d 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1466,6 +1466,27 @@ key removed from @file{.guix-authorizations} after 12 months of
 inactivity; they can ask to regain commit access by emailing the
 maintainers, without going through the vouching process.
 
+Maintainers@footnote{See @uref{https://guix.gnu.org/en/about} for the
+current list of maintainers.  You can email them privately at
+@email{guix-maintainers@@gnu.org}.} may also revoke an individual's
+commit rights, as a last resort, if cooperation with the rest of the
+community has caused too much friction---even within the bounds of the
+project's code of conduct (@pxref{Contributing}).  They would only do so
+after public or private discussion with the individual and a clear
+notice.  Examples of behavior that hinders cooperation and could lead to
+such a decision include:
+
+@itemize
+@item repeated violation of the commit policy stated above;
+@item repeated failure to take peer criticism into account;
+@item breaching trust through a series of grave incidents.
+@end itemize
+
+When maintainers resort to such a decision, they notify developers on
+@email{guix-devel@@gnu.org}; inquiries may be sent to
+@email{guix-maintainers@@gnu.org}.  Depending on the situation, the
+individual may still be welcome to contribute.
+
 @subsection Helping Out
 
 One last thing: the project keeps moving forward because committers not
-- 
cgit v1.2.3


From b5b9266e409abb18970bd34557cf087eb29fa713 Mon Sep 17 00:00:00 2001
From: Ludovic Courtès <ludo@gnu.org>
Date: Sun, 13 Jun 2021 12:09:40 +0200
Subject: doc: Clarify Git commit signing; fix typo.

Suggested by Maxime Devos <maximedevos@telenet.be>
and Julien Lepiller <julien@lepiller.eu>.

* doc/contributing.texi (Commit Access): Clarify Git commit signing
setup and fix typo.
---
 doc/contributing.texi | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 9e574f8b5d..e612ea7b23 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1367,11 +1367,13 @@ commits, run:
 
 @example
 git config commit.gpgsign true
+
+# Substitute the fingerprint of your public PGP key.
 git config user.signingkey CABBA6EA1DC0FF33
 @end example
 
 You can prevent yourself from accidentally pushing unsigned commits to
-Savannah by using the pre-push Git hook called located at
+Savannah by using the pre-push Git hook located at
 @file{etc/git/pre-push}:
 
 @example
-- 
cgit v1.2.3