Subject: Re: bug#36785: Impossible to pull on foreign distro

From: Maxim Cournoyer <[email-masked]>
Date: Sat, 28 Sep 2019 00:23:34 +0900

Hi!

Ludovic Courtès <[email-masked]> writes:

[...]

> It’s a paragraph that explains how to upgrade Guix System, so I think
> foreign distros should be discussed elsewhere.  (I appreciate your
> attempt to add proper documentation about that for foreign distros!)
>
>> what my commits aim to do is make them generally true regardless of
>> In the commit message I wrote:
>>
>>    Although this section is specific to Guix System, it is likely to be
>>    read by users of foreign GNU/Linux distributions as well.  Remove the
>>    note, given that sudo doesn't preserve the user's PATH on foreign
>>    distributions such as Debian.
>
> But users of foreign distros would hopefully realize that ‘guix system
> reconfigure’ (in the same snippet) is not for them.  :-)

I've been guilty myself of using C-s or 'i' in the manual and reading
something that didn't apply to my system but *did* match my
search... :-) 

>> What about adding a section that we could call “Upgrading Guix”
> under “Application Setup”, which is where setup on foreign distros is
> discussed?
>
> The section could say:
>
>   1. Run ‘guix pull’ to upgrade Guix.
>
>   2. When you need to upgrade the build daemon, for instance, which runs
>      as root, run:
>
>        sudo -i guix pull
>
> How does that sound?

This sounds much simpler than attempting to twist some other section
into something it wasn't really meant for ;-).

I've attached a simple patch implementing the idea.

Thanks for your patience!

Maxim

>From a289eb3fd6239287d4a802fbba69abf21604591f Mon Sep 17 00:00:00 2001
From: Maxim Cournoyer <[email-masked]>
Date: Sat, 28 Sep 2019 00:11:28 +0900
Subject: [PATCH] doc: Add a 'Upgrading Guix' section to the 'Installation'
 chapter.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This follows a discussion regarding issue #36785 (see:
https://bugs.gnu.org/36785).

* doc/guix.texi (Upgrading Guix): New section.

Co-authored-by: Ludovic Courtès <[email-masked]>
---
 doc/guix.texi | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 9fcce27597..45e6dfc442 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -513,6 +513,7 @@ ready to use it.
 * Setting Up the Daemon::       Preparing the build daemon's environment.
 * Invoking guix-daemon::        Running the build daemon.
 * Application Setup::           Application-specific setup.
+* Upgrading Guix::              Upgrading Guix and its build daemon.
 @end menu
 
 @node Binary Installation
@@ -1777,6 +1778,28 @@ invoke the actual linker with this new set of arguments.  You can instruct the
 wrapper to refuse to link against libraries not in the store by setting the
 @code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}.
 
+@node Upgrading Guix
+@section Upgrading Guix
+
+@cindex Upgrading Guix, on a foreign distro
+
+To upgrade Guix, run:
+
+@example
+guix pull
+@end example
+
+@cindex Upgrading Guix for the root user, on a foreign distro
+@cindex Upgrading the Guix daemon, on a foreign distro
+@cindex @command{guix pull} for the root user, on a foreign distro
+
+When you need to upgrade the build daemon, for instance, which runs as
+root, run:
+
+@example
+sudo -i guix pull
+@end example
+
 @c TODO What else?
 
 @c *********************************************************************
-- 
2.23.0