bug#24993: Documentation: 'guix pull' needed during SD installation

[Leo Famulari <leo@famulari.name>]

On Tue, Nov 22, 2016 at 01:25:57PM -0900, Christopher Howard wrote:

Welcome Christopher!

> In the online installation docs at
> <https://www.gnu.org/software/guix/manual/html_node/Proceeding-with-the-Installation.html#Proceeding-with-the-Installation>,
> please insert the command 'guix pull' before the "guix system init"
> command. Otherwise installation can fail due to missing binary packages,
> which creates confusion for newbie installers like myself. Thank you!

Can you give more detail about the problems you ran into? We want `guix
system init` to "just work".

In general, if some binary fails to be substituted [0], adding
--fallback to the command should cause the package to be built from
source, working around the issue.

I think that running `guix pull` before `guix system init` is not the
right choice for newbies, although there are some trade-offs [1].

Most new users will be installing from the binary GuixSD installer
offered on our web site. This installer is built from a Git commit that
we have tested to ensure that everything should work. We strive to keep
our master branch "deployable", but of course we make mistakes
sometimes. `guix pull` draws from the HEAD commit of the master branch,
and so new users might end up with a broken system as their first
experience.  GuixSD is extremely robust once installed — you can always
roll-back — so it's a good idea to initialize from a known good commit
and then update.

Additionally, it's likely that we will not yet have built binary
substitutes for the most recent changes on the master branch, so new
users will end up building some things from source if they use `guix
pull`.

[0] Guix is a hybrid of build-from-source and binary package management
systems. It's really a build-from-source distro, but we offer so-called
"binary substitutes", and they are transparently substituted for a
source build if they are available and the user has authorized our
substitutes server. But, if Guix expects a package to be substituted
and something goes wrong, the action will fail. Using --fallback works
around this and builds from source even when the substitution fails.

[1] I think the main drawback of installing from the release tag without
`guix pull` is that the initial generation of the GuixSD system will be
lacking important upstream bug fixes. I think users should `guix pull &&
guix system reconfigure` immediately after initializing the system. Guix
actually nags users to do this:

http://git.savannah.gnu.org/cgit/guix.git/tree/guix/scripts/system.scm?id=08b3e4a97066c9baaf39e3df7c2dd9c39e693ead#n577