GNU bug report logs - #29271
[PATCH 0/1] Improve the "Substitutes" documentation

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 29271 in the body.
You can then email your comments to 29271 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Chris Marusich <cmmarusich <at> gmail.com>
To: guix-patches <at> gnu.org
Cc: myglc2 <at> gmail.com, Chris Marusich <cmmarusich <at> gmail.com>, leo <at> famulari.name
Subject: [PATCH 0/1] Improve the "Substitutes" documentation
Date: Sun, 12 Nov 2017 03:02:33 -0800

Hi Guix,

Attached is a patch which attempts to improve the clarity of the
Substitutes section by moving its content into subsections.  I have
also taken the liberty of adding some new information, which should
clarify (1) the question of whether or not substitutes are enabled by
default, and (2) the --fallback option.  The following email thread
demonstrates that this information was not clear enough, so hopefully
it is clear enough now:

https://lists.gnu.org/archive/html/help-guix/2017-11/msg00032.html

Best regards,

Chris Marusich (1):
  doc: Split the "Substitutes" section into subsections.

 doc/guix.texi | 126 +++++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 94 insertions(+), 32 deletions(-)

-- 
2.14.2

Message #8 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Chris Marusich <cmmarusich <at> gmail.com>
To: guix-patches <at> gnu.org
Cc: myglc2 <at> gmail.com, Chris Marusich <cmmarusich <at> gmail.com>, leo <at> famulari.name
Subject: [PATCH 1/1] doc: Split the "Substitutes" section into subsections.
Date: Sun, 12 Nov 2017 03:05:58 -0800

* doc/guix.texi (Substitutes): Move information into sections, and create one
  new subsection regarding substitution failure.
  (Top): In the detailed listing, add entries for the new subsections.
  (Hydra): Move info about Hydra here.  Add information that explains when
  substitutes are enabled by default.
  (Substitute Server Authorization): Move information about how to enable or
  disable substitutes here.
  (Substitute Authentication): Move information about how Guix authenticates
  substitutes here.
  (Proxy Settings): Move information about how to download substitutes via
  proxy here.
  (Substitution Failure): New section.  Add information about how Guix handles
  substitution failure.  Be extra clear about behavior concerning --fallback.
  (On Trusting Binaries): Move information about trusting binaries here.
  (Invoking guix-daemon): Remove an incorrect statement about when substitutes
  are enabled by default.
  (Common Build Options): Clarify the behavior of --fallback.

Co-authored-by: myglc2 <myglc2 <at> gmail.com>
---
 doc/guix.texi | 126 +++++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 94 insertions(+), 32 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 11a9de689..404ea2406 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -130,6 +130,15 @@ Package Management
 * Invoking guix pack::          Creating software bundles.
 * Invoking guix archive::       Exporting and importing store files.
 
+Substitutes
+
+* Hydra::                           One particular source of substitutes.
+* Substitute Server Authorization:: How to enable or disable substitutes.
+* Substitute Authentication::       How Guix verifies substitutes.
+* Proxy Settings::                  How to get substitutes via proxy.
+* Substitution Failure::            What happens when substitution fails.
+* On Trusting Binaries::            How can you trust that binary blob?
+
 Programming Interface
 
 * Defining Packages::           Defining new packages.
@@ -1108,10 +1117,6 @@ Do not use substitutes for build products.  That is, always build things
 locally instead of allowing downloads of pre-built binaries
 (@pxref{Substitutes}).
 
-By default substitutes are used, unless the client---such as the
-@command{guix package} command---is explicitly invoked with
-@code{--no-substitutes}.
-
 When the daemon runs with @code{--no-substitutes}, clients can still
 explicitly enable substitution @i{via} the @code{set-build-options}
 remote procedure call (@pxref{The Store}).
@@ -2108,7 +2113,6 @@ preserve transformations across upgrades, you should define your own
 package variant in a Guile module and add it to @code{GUIX_PACKAGE_PATH}
 (@pxref{Defining Packages}).
 
-
 @node Substitutes
 @section Substitutes
 
@@ -2116,8 +2120,8 @@ package variant in a Guile module and add it to @code{GUIX_PACKAGE_PATH}
 @cindex pre-built binaries
 Guix supports transparent source/binary deployment, which means that it
 can either build things locally, or download pre-built items from a
-server.  We call these pre-built items @dfn{substitutes}---they are
-substitutes for local build results.  In many cases, downloading a
+server, or both.  We call these pre-built items @dfn{substitutes}---they
+are substitutes for local build results.  In many cases, downloading a
 substitute is much faster than building things locally.
 
 Substitutes can be anything resulting from a derivation build
@@ -2125,6 +2129,20 @@ Substitutes can be anything resulting from a derivation build
 pre-built package binaries, but source tarballs, for instance, which
 also result from derivation builds, can be available as substitutes.
 
+@menu
+* Hydra::                           One particular source of substitutes.
+* Substitute Server Authorization:: How to enable or disable substitutes.
+* Substitute Authentication::       How Guix verifies substitutes.
+* Proxy Settings::                  How to get substitutes via proxy.
+* Substitution Failure::            What happens when substitution fails.
+* On Trusting Binaries::            How can you trust that binary blob?
+@end menu
+
+@node Hydra
+@subsection Hydra
+
+@cindex hydra
+@cindex build farm
 The @code{hydra.gnu.org} server is a front-end to a build farm that
 builds packages from the GNU distribution continuously for some
 architectures, and makes them available as substitutes.  This is the
@@ -2141,9 +2159,19 @@ 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 Hydra are enabled by default when using the Guix System
+Distribution (@pxref{GNU Distribution}).  However, substitutes are
+disabled by default when using Guix on a foreign distribution
+(@pxref{Installation}).  The following paragraphs describe how to enable
+or disable substitutes for Hydra; the same procedure can also be used to
+enable substitutes for any other substitute server.
+
+
+@node Substitute Server Authorization
+@subsection Substitute Server Authorization
+
 @cindex security
-@cindex digital signatures
-@cindex substitutes, authorization thereof
+@cindex substitutes, how to enable
 @cindex access control list (ACL), for substitutes
 @cindex ACL (access control list), for substitutes
 To allow Guix to download substitutes from @code{hydra.gnu.org} or a
@@ -2153,7 +2181,7 @@ imports, using the @command{guix archive} command (@pxref{Invoking guix
 archive}).  Doing so implies that you trust @code{hydra.gnu.org} to not
 be compromised and to serve genuine substitutes.
 
-This public key is installed along with Guix, in
+Hydra's public key is installed along with Guix, in
 @code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is
 the installation prefix of Guix.  If you installed Guix from source,
 make sure you checked the GPG signature of
@@ -2194,6 +2222,17 @@ The following files would be downloaded:
 This indicates that substitutes from @code{hydra.gnu.org} 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
+@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
+guix-daemon}).  It can also be disabled temporarily by passing the
+@code{--no-substitutes} option to @command{guix package}, @command{guix
+build}, and other command-line tools.
+
+@node Substitute Authentication
+@subsection Substitute Authentication
+
+@cindex digital signatures
 Guix detects and raises an error when attempting to use a substitute
 that has been tampered with.  Likewise, it ignores substitutes that are
 not signed, or that are not signed by one of the keys listed in the ACL.
@@ -2218,15 +2257,6 @@ comes first in the list and can be considered a mirror of
 produce the same binaries, thanks to bit-reproducible builds (see
 below).
 
-@vindex http_proxy
-Substitutes are downloaded over HTTP or HTTPS.
-The @code{http_proxy} environment
-variable can be set in the environment of @command{guix-daemon} and is
-honored for downloads of substitutes.  Note that the value of
-@code{http_proxy} in the environment where @command{guix build},
-@command{guix package}, and other client commands are run has
-@emph{absolutely no effect}.
-
 When using HTTPS, the server's X.509 certificate is @emph{not} validated
 (in other words, the server is not authenticated), contrary to what
 HTTPS clients such as Web browsers usually do.  This is because Guix
@@ -2234,18 +2264,49 @@ authenticates substitute information itself, as explained above, which
 is what we care about (whereas X.509 certificates are about
 authenticating bindings between domain names and public keys.)
 
-You can get statistics on the substitutes provided by a server using the
-@command{guix weather} command (@pxref{Invoking guix weather}).
-
-The substitute mechanism can be disabled globally by running
-@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
-guix-daemon}).  It can also be disabled temporarily by passing the
-@code{--no-substitutes} option to @command{guix package}, @command{guix
-build}, and other command-line tools.
-
+@node Proxy Settings
+@subsection Proxy Settings
 
-@unnumberedsubsec On Trusting Binaries
+@vindex http_proxy
+Substitutes are downloaded over HTTP or HTTPS.
+The @code{http_proxy} environment
+variable can be set in the environment of @command{guix-daemon} and is
+honored for downloads of substitutes.  Note that the value of
+@code{http_proxy} in the environment where @command{guix build},
+@command{guix package}, and other client commands are run has
+@emph{absolutely no effect}.
 
+@node Substitution Failure
+@subsection Substitution Failure
+
+Even when a substitute for a derivation is available, sometimes the
+substitution attempt will fail.  This can happen for a variety of
+reasons: the substitute server might be offline, the substitute may
+recently have been deleted, the connection might have been interrupted,
+etc.
+
+When substitutes are enabled and a substitute for a derivation is
+available, but the substitution attempt fails, Guix will attempt to
+build the derivation locally depending on whether or not
+@code{--fallback} was given (@pxref{fallback-option}).  Specifically, if
+@code{--fallback} was omitted, then no local build will be performed,
+and the derivation is considered to have failed.  However, if
+@code{--fallback} was given, then Guix will attempt to build the
+derivation locally, and the success or failure of the derivation depends
+on the success or failure of the local build.  Note that when
+substitutes are disabled or no substitute is available for the
+derivation in question, a local build will @emph{always} be performed,
+regardless of whether or not @code{--fallback} was given.
+
+To get an idea of how many substitutes are available right now, you can
+try running the @command{guix weather} command (@pxref{Invoking guix
+weather}).  This command provides statistics on the substitutes provided
+by a server.
+
+@node On Trusting Binaries
+@subsection On Trusting Binaries
+
+@cindex trust, of pre-built binaries
 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
@@ -2272,7 +2333,6 @@ In the future, we want Guix to have support to publish and retrieve
 binaries to/from other users, in a peer-to-peer fashion.  If you would
 like to discuss this project, join us on @email{guix-devel@@gnu.org}.
 
-
 @node Packages with Multiple Outputs
 @section Packages with Multiple Outputs
 
@@ -5191,9 +5251,11 @@ derivations has failed.
 @itemx -n
 Do not build the derivations.
 
+@anchor{fallback-option}
 @item --fallback
-When substituting a pre-built binary fails, fall back to building
-packages locally.
+Attempt to build locally instead of issuing an error when substitutes
+are enabled and a substitute is available, but the substitution attempt
+fails (@pxref{Substitution Failure}).
 
 @item --substitute-urls=@var{urls}
 @anchor{client-substitute-urls}
-- 
2.14.2

Message #11 received at 29271 <at> debbugs.gnu.org (full text, mbox):

From: Adonay Felipe Nogueira <adfeno <at> hyperbola.info>
To: 29271 <at> debbugs.gnu.org
Subject: Re: [bug#29271] [PATCH 0/1] Improve the "Substitutes" documentation
Date: Sun, 12 Nov 2017 09:21:27 -0200

Nice work! ;)

Chris Marusich <cmmarusich <at> gmail.com> writes:

> Hi Guix,
>
> Attached is a patch which attempts to improve the clarity of the
> Substitutes section by moving its content into subsections.  I have
> also taken the liberty of adding some new information, which should
> clarify (1) the question of whether or not substitutes are enabled by
> default, and (2) the --fallback option.  The following email thread
> demonstrates that this information was not clear enough, so hopefully
> it is clear enough now:
>
> https://lists.gnu.org/archive/html/help-guix/2017-11/msg00032.html
>
> Best regards,
>
> Chris Marusich (1):
>   doc: Split the "Substitutes" section into subsections.
>
>  doc/guix.texi | 126 +++++++++++++++++++++++++++++++++++++++++++---------------
>  1 file changed, 94 insertions(+), 32 deletions(-)

-- 
- https://libreplanet.org/wiki/User:Adfeno
- Palestrante e consultor sobre /software/ livre (não confundir com
  gratis).
- "WhatsApp"? Ele não é livre. Por favor, veja formas de se comunicar
  instantaneamente comigo no endereço abaixo.
- Contato: https://libreplanet.org/wiki/User:Adfeno#vCard
- Arquivos comuns aceitos (apenas sem DRM): Corel Draw, Microsoft
  Office, MP3, MP4, WMA, WMV.
- Arquivos comuns aceitos e enviados: CSV, GNU Dia, GNU Emacs Org, GNU
  GIMP, Inkscape SVG, JPG, LibreOffice (padrão ODF), OGG, OPUS, PDF
  (apenas sem DRM), PNG, TXT, WEBM.

Message #14 received at 29271 <at> debbugs.gnu.org (full text, mbox):

From: Jan Nieuwenhuizen <janneke <at> gnu.org>
To: Chris Marusich <cmmarusich <at> gmail.com>
Cc: 29271 <at> debbugs.gnu.org, myglc2 <at> gmail.com
Subject: Re: [bug#29271] [PATCH 1/1] doc: Split the "Substitutes" section into
 subsections.
Date: Sun, 12 Nov 2017 14:56:23 +0100

Chris Marusich writes:

> +Substitutes from Hydra are enabled by default when using the Guix System
> +Distribution (@pxref{GNU Distribution}).  However, substitutes are
> +disabled by default when using Guix on a foreign distribution
> +(@pxref{Installation}).

It's great to have this clarified, however I wonder about the rationale
of this decision?

janneke

-- 
Jan Nieuwenhuizen <janneke <at> gnu.org> | GNU LilyPond http://lilypond.org
Freelance IT http://JoyofSource.com | Avatar® http://AvatarAcademy.com

Message #17 received at 29271 <at> debbugs.gnu.org (full text, mbox):

From: Leo Famulari <leo <at> famulari.name>
To: Jan Nieuwenhuizen <janneke <at> gnu.org>
Cc: 29271 <at> debbugs.gnu.org, Chris Marusich <cmmarusich <at> gmail.com>,
 myglc2 <at> gmail.com
Subject: Re: [bug#29271] [PATCH 1/1] doc: Split the "Substitutes" section
 into subsections.
Date: Sun, 12 Nov 2017 15:25:06 -0500

[Message part 1 (text/plain, inline)]

On Sun, Nov 12, 2017 at 02:56:23PM +0100, Jan Nieuwenhuizen wrote:
> Chris Marusich writes:
> 
> > +Substitutes from Hydra are enabled by default when using the Guix System
> > +Distribution (@pxref{GNU Distribution}).  However, substitutes are
> > +disabled by default when using Guix on a foreign distribution
> > +(@pxref{Installation}).
> 
> It's great to have this clarified, however I wonder about the rationale
> of this decision?

Copied from my previous message [0]:

------
I don't know if there is a design choice here, but the steps required to
authorize substitutes for Guix on another distro require root. So, we
can't make it "just work" without the user elevating their privileges.
It's not the only part of our installation guide that requires root,
however.

On GuixSD, we can control the entire system during installation, so we
enable substitutes by default.
------

[0]
https://lists.gnu.org/archive/html/help-guix/2017-11/msg00048.html

[signature.asc (application/pgp-signature, inline)]

Message #20 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Leo Famulari <leo <at> famulari.name>
To: Chris Marusich <cmmarusich <at> gmail.com>
Cc: myglc2 <at> gmail.com, guix-patches <at> gnu.org
Subject: Re: [PATCH 1/1] doc: Split the "Substitutes" section into subsections.
Date: Sun, 12 Nov 2017 15:36:44 -0500

[Message part 1 (text/plain, inline)]

On Sun, Nov 12, 2017 at 03:05:58AM -0800, Chris Marusich wrote:
> * doc/guix.texi (Substitutes): Move information into sections, and create one
>   new subsection regarding substitution failure.
>   (Top): In the detailed listing, add entries for the new subsections.
>   (Hydra): Move info about Hydra here.  Add information that explains when
>   substitutes are enabled by default.
>   (Substitute Server Authorization): Move information about how to enable or
>   disable substitutes here.
>   (Substitute Authentication): Move information about how Guix authenticates
>   substitutes here.
>   (Proxy Settings): Move information about how to download substitutes via
>   proxy here.
>   (Substitution Failure): New section.  Add information about how Guix handles
>   substitution failure.  Be extra clear about behavior concerning --fallback.
>   (On Trusting Binaries): Move information about trusting binaries here.
>   (Invoking guix-daemon): Remove an incorrect statement about when substitutes
>   are enabled by default.
>   (Common Build Options): Clarify the behavior of --fallback.

Hi, thanks for your efforts to improve the documentation.

Personally, I find it impossible to read diffs of natural language text;
it just doesn't work for me like it does with code.

So, I will just ask, does this duplicate instructions regarding
substitutes in other sections? We should be careful to avoid that.

> +@anchor{fallback-option}
>  @item --fallback
> -When substituting a pre-built binary fails, fall back to building
> -packages locally.
> +Attempt to build locally instead of issuing an error when substitutes
> +are enabled and a substitute is available, but the substitution attempt
> +fails (@pxref{Substitution Failure}).

I was able to read this smaller change. I think the new sentence is too
byzantine. I know what --fallback does but I found this sentence hard to
understand.

The condition that determines whether we "attempt to build locally"
should be at the beginning of the sentence, like this:

"When substitutes are enabled and a substitute is available, but the
substitution fails, fall back to building the derivation locally."

This is basically the same as before, but with some more detail about
the condition.

[signature.asc (application/pgp-signature, inline)]

Message #23 received at 29271 <at> debbugs.gnu.org (full text, mbox):

From: Eric Bavier <ericbavier <at> centurylink.net>
To: Leo Famulari <leo <at> famulari.name>
Cc: 29271 <at> debbugs.gnu.org, Chris Marusich <cmmarusich <at> gmail.com>,
 myglc2 <at> gmail.com
Subject: Re: [bug#29271] [PATCH 1/1] doc: Split the "Substitutes" section
 into subsections.
Date: Sun, 12 Nov 2017 13:17:25 -0600

[Message part 1 (text/plain, inline)]

On Sun, 12 Nov 2017 15:36:44 -0500
Leo Famulari <leo <at> famulari.name> wrote:

> On Sun, Nov 12, 2017 at 03:05:58AM -0800, Chris Marusich wrote:
> > +@anchor{fallback-option}
> >  @item --fallback
> > -When substituting a pre-built binary fails, fall back to building
> > -packages locally.
> > +Attempt to build locally instead of issuing an error when substitutes
> > +are enabled and a substitute is available, but the substitution attempt
> > +fails (@pxref{Substitution Failure}).  
> 
> I was able to read this smaller change. I think the new sentence is too
> byzantine. I know what --fallback does but I found this sentence hard to
> understand.

Same here.

> 
> The condition that determines whether we "attempt to build locally"
> should be at the beginning of the sentence, like this:
> 
> "When substitutes are enabled and a substitute is available, but the
> substitution fails, fall back to building the derivation locally."
> 
> This is basically the same as before, but with some more detail about
> the condition.

IMHO, the original text is just fine, and succinctly conveys the
origin of the option name. Perhaps just add the cross reference.

`~Eric

[Message part 2 (application/pgp-signature, inline)]

Message #26 received at 29271 <at> debbugs.gnu.org (full text, mbox):

From: myglc2 <myglc2 <at> gmail.com>
To: Leo Famulari <leo <at> famulari.name>
Cc: 29271 <at> debbugs.gnu.org, Chris Marusich <cmmarusich <at> gmail.com>,
 Jan Nieuwenhuizen <janneke <at> gnu.org>
Subject: Re: [bug#29271] [PATCH 1/1] doc: Split the "Substitutes" section into
 subsections.
Date: Mon, 13 Nov 2017 09:37:08 -0500

On 11/12/2017 at 20:25 Leo Famulari writes:

> On Sun, Nov 12, 2017 at 02:56:23PM +0100, Jan Nieuwenhuizen wrote:
>> Chris Marusich writes:
>>
>> > +Substitutes from Hydra are enabled by default when using the Guix System
>> > +Distribution (@pxref{GNU Distribution}).  However, substitutes are
>> > +disabled by default when using Guix on a foreign distribution
>> > +(@pxref{Installation}).
>>
>> It's great to have this clarified, however I wonder about the rationale
>> of this decision?
>
> Copied from my previous message [0]:
>
> ------
> I don't know if there is a design choice here, but the steps required to
> authorize substitutes for Guix on another distro require root. So, we
> can't make it "just work" without the user elevating their privileges.
> It's not the only part of our installation guide that requires root,
> however.
>
> On GuixSD, we can control the entire system during installation, so we
> enable substitutes by default.
> ------
>
> [0]
> https://lists.gnu.org/archive/html/help-guix/2017-11/msg00048.html

ISTM that "disabled by default when using Guix on a foreign
distribution" is too strong. How about ...

Substitutes from Hydra are enabled by default in the Guix System
Distribution (@pxref{GNU Distribution}) and by one of the recommended
installation steps for Guix on a foreign distribution
(@pxref{Installation}).

- George

Message #29 received at 29271 <at> debbugs.gnu.org (full text, mbox):

From: myglc2 <myglc2 <at> gmail.com>
To: Chris Marusich <cmmarusich <at> gmail.com>
Cc: 29271 <at> debbugs.gnu.org, leo <at> famulari.name
Subject: Re: [bug#29271] [PATCH 1/1] doc: Split the "Substitutes" section into
 subsections.
Date: Mon, 13 Nov 2017 12:27:32 -0500

Chris,

I installed the patch and read the sections. This is great stuff.

In addition to the minor suggestion in a sub-thread, how about
replacing...

> +When substitutes are enabled and a substitute for a derivation is
> +available, but the substitution attempt fails, Guix will attempt to
> +build the derivation locally depending on whether or not
> +@code{--fallback} was given (@pxref{fallback-option}).  Specifically, if
> +@code{--fallback} was omitted, then no local build will be performed,
> +and the derivation is considered to have failed.  However, if
> +@code{--fallback} was given, then Guix will attempt to build the
> +derivation locally, and the success or failure of the derivation depends
> +on the success or failure of the local build.  Note that when

... with...

When substitutes are enabled and a substitute for a derivation is
available, but the substitution attempt fails, Guix will report an error
unless the @code{--fallback} was given (@pxref{fallback-option}), in
which case Guix will attempt to build the derivation locally Note that
when

HTH - George

Message #32 received at 29271 <at> debbugs.gnu.org (full text, mbox):

From: Chris Marusich <cmmarusich <at> gmail.com>
To: myglc2 <myglc2 <at> gmail.com>
Cc: 29271 <at> debbugs.gnu.org, Jan Nieuwenhuizen <janneke <at> gnu.org>,
 Leo Famulari <leo <at> famulari.name>
Subject: Re: [bug#29271] [PATCH 1/1] doc: Split the "Substitutes" section into
 subsections.
Date: Tue, 14 Nov 2017 21:21:05 -0800

[Message part 1 (text/plain, inline)]

Hi everyone,

Thank you for taking the time to review my patch!

myglc2 <myglc2 <at> gmail.com> writes:

> On 11/12/2017 at 20:25 Leo Famulari writes:
>
> ISTM that "disabled by default when using Guix on a foreign
> distribution" is too strong. How about ...
>
> Substitutes from Hydra are enabled by default in the Guix System
> Distribution (@pxref{GNU Distribution}) and by one of the recommended
> installation steps for Guix on a foreign distribution
> (@pxref{Installation}).

What if we say something like "disabled by default when using Guix on a
foreign distro, unless you've explicitly enabled them via one of the
recommended installation steps (@pxref{Installation})"?  Let me know if
you think that would be OK.

I want to clarify the fact that the substitutes are disabled by default
when installing Guix on a foreign distro.  That's a bit surprising, and
it needs to be clear.  At the same time, I think it's good to remind
users that they are in full control and can enable the substitutes
easily.

Leo Famulari <leo <at> famulari.name> writes:

> Personally, I find it impossible to read diffs of natural language text;
> it just doesn't work for me like it does with code.
>
> So, I will just ask, does this duplicate instructions regarding
> substitutes in other sections? We should be careful to avoid that.

No, there is no duplication (as far as I can tell!).  90% of this commit
is about moving existing text into subsections.  9% is the new
sub-section "Substitution Failure", and 1% is minor adjustments
elsewhere (e.g., removing an incorrect statement from the "Invoking
guix-daemon" section).

If this were code, I might have broken it out more into separate
commits, but since the GNU standards explicitly say that we don't even
need ChangeLog entries for documentation, I think it's OK to
conveniently squish these changes into one commit.

>> +@anchor{fallback-option}
>>  @item --fallback
>> -When substituting a pre-built binary fails, fall back to building
>> -packages locally.
>> +Attempt to build locally instead of issuing an error when substitutes
>> +are enabled and a substitute is available, but the substitution attempt
>> +fails (@pxref{Substitution Failure}).
>
> I was able to read this smaller change. I think the new sentence is too
> byzantine. I know what --fallback does but I found this sentence hard to
> understand.
>
> The condition that determines whether we "attempt to build locally"
> should be at the beginning of the sentence, like this:
>
> "When substitutes are enabled and a substitute is available, but the
> substitution fails, fall back to building the derivation locally."
>
> This is basically the same as before, but with some more detail about
> the condition.

I agree that is better, as long as we include a cross-reference to the
more detailed "Substitution Failure" section (which is what Eric
suggested).  I'll update the patch along those lines.

myglc2 <myglc2 <at> gmail.com> writes:

> Chris,
>
> I installed the patch and read the sections. This is great stuff.
>
> In addition to the minor suggestion in a sub-thread, how about
> replacing...
>
>> +When substitutes are enabled and a substitute for a derivation is
>> +available, but the substitution attempt fails, Guix will attempt to
>> +build the derivation locally depending on whether or not
>> +@code{--fallback} was given (@pxref{fallback-option}).  Specifically, if
>> +@code{--fallback} was omitted, then no local build will be performed,
>> +and the derivation is considered to have failed.  However, if
>> +@code{--fallback} was given, then Guix will attempt to build the
>> +derivation locally, and the success or failure of the derivation depends
>> +on the success or failure of the local build.  Note that when
>
> ... with...
>
> When substitutes are enabled and a substitute for a derivation is
> available, but the substitution attempt fails, Guix will report an error
> unless the @code{--fallback} was given (@pxref{fallback-option}), in
> which case Guix will attempt to build the derivation locally Note that
> when

Personally, I prefer the more detailed explanation because it's less
ambiguous.  What does "report an error" mean?  To those who already
know, it might be clear, but to someone who is learning for the first
time, the ambiguity is unhelpful.

However, if others prefer the less verbose wording, I will use it.
What do you think, Leo and Eric?

-- 
Chris

[signature.asc (application/pgp-signature, inline)]

Message #35 received at 29271 <at> debbugs.gnu.org (full text, mbox):

From: myglc2 <myglc2 <at> gmail.com>
To: Chris Marusich <cmmarusich <at> gmail.com>
Cc: 29271 <at> debbugs.gnu.org, Leo Famulari <leo <at> famulari.name>,
 Jan Nieuwenhuizen <janneke <at> gnu.org>
Subject: Re: [bug#29271] [PATCH 1/1] doc: Split the "Substitutes" section into
 subsections.
Date: Wed, 15 Nov 2017 08:31:28 -0500

On 11/14/2017 at 21:21 Chris Marusich writes:

[...]
>> Substitutes from Hydra are enabled by default in the Guix System
>> Distribution (@pxref{GNU Distribution}) and by one of the recommended
>> installation steps for Guix on a foreign distribution
>> (@pxref{Installation}).
>
> What if we say something like "disabled by default when using Guix on a
> foreign distro, unless you've explicitly enabled them via one of the
> recommended installation steps (@pxref{Installation})"?  Let me know if
> you think that would be OK.

LGTM! Thanks for doing this. - George

Message #38 received at 29271 <at> debbugs.gnu.org (full text, mbox):

From: ludo <at> gnu.org (Ludovic Courtès)
To: Eric Bavier <ericbavier <at> centurylink.net>
Cc: 29271 <at> debbugs.gnu.org, Chris Marusich <cmmarusich <at> gmail.com>,
 myglc2 <at> gmail.com, Leo Famulari <leo <at> famulari.name>
Subject: Re: [bug#29271] [PATCH 1/1] doc: Split the "Substitutes" section into
 subsections.
Date: Mon, 20 Nov 2017 23:40:53 +0100

Hello!

Eric Bavier <ericbavier <at> centurylink.net> skribis:

> On Sun, 12 Nov 2017 15:36:44 -0500
> Leo Famulari <leo <at> famulari.name> wrote:
>
>> On Sun, Nov 12, 2017 at 03:05:58AM -0800, Chris Marusich wrote:
>> > +@anchor{fallback-option}
>> >  @item --fallback
>> > -When substituting a pre-built binary fails, fall back to building
>> > -packages locally.
>> > +Attempt to build locally instead of issuing an error when substitutes
>> > +are enabled and a substitute is available, but the substitution attempt
>> > +fails (@pxref{Substitution Failure}).  
>> 
>> I was able to read this smaller change. I think the new sentence is too
>> byzantine. I know what --fallback does but I found this sentence hard to
>> understand.
>
> Same here.

[...]

> IMHO, the original text is just fine, and succinctly conveys the
> origin of the option name. Perhaps just add the cross reference.

I agree, but I’m biased.  ;-)

Apart from that, the rest LGTM.  I have one minor request:

> +* Hydra::                           One particular source of substitutes.

I would call this “Official Substitute Server” or something like that,
and not mention Hydra (as a proper noun) since we’re not defining it,
and since the server won’t run Hydra forever.

With these two changes, I think you can push.

Thanks for improving the manual!

Ludo’.

Message #43 received at 29271-done <at> debbugs.gnu.org (full text, mbox):

From: Chris Marusich <cmmarusich <at> gmail.com>
To: bug#29271 <29271-done <at> debbugs.gnu.org>
Subject: Re: Status: [PATCH 0/1] Improve the "Substitutes" documentation
Date: Tue, 21 Nov 2017 20:29:29 -0800

[Message part 1 (text/plain, inline)]

Hi,

I've committed this as 77f921587c6b784e84b98a9f2e9c821f73114340.  This
commit includes the minor changes suggested by Ludo.

In particular, I used the phrase "official build server" instead of
"hydra" where applicable; I simply added a cross-reference to the
description of the --fallback option instead of making it more verbose;
and I changed the language describing how substitutes are disabled by
default when Guix is installed on a foreign distro to emphasize the fact
that our recommended installation steps will enable them anyway.

If anyone has any concerns, please let me know.

-- 
Chris

[signature.asc (application/pgp-signature, inline)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.