GNU bug report logs - #69977
[PATCH] doc: doc-Simplify installation instructions (was Re: doc: installation: fix ~root confusion (was Re: doc: Removing much of Binary Installation))

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 69977 in the body.
You can then email your comments to 69977 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: Matt <matt <at> excalamus.com>
To: "guix-patches" <guix-patches <at> gnu.org>
Cc: Josselin Poiret <dev <at> jpoiret.xyz>,
 Christian Miller <christian.miller <at> dadoes.de>,
 Maxim Cournoyer <maxim.cournoyer <at> gmail.com>,
 "pelzflorian \(Florian Pelz\)" <pelzflorian <at> pelzflorian.de>
Subject: [PATCH] doc: doc-Simplify installation instructions (was Re: doc:
 installation: fix ~root confusion (was Re: doc: Removing much of Binary
 Installation))
Date: Sun, 24 Mar 2024 10:27:30 +0100

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

On Ludo's recommendation, I'm submitting this patch set.  It fixes issues of confusion raised in feedback on the manual.  See this discussion: https://lists.gnu.org/archive/html/guix-devel/2024-03/msg00023.html

I will reply to points raised in that thread here and have CC'd people who have previously shown interest.

 ---- On Sat, 16 Mar 2024 15:05:13 +0100  pelzflorian (Florian Pelz)  wrote ---
 > I think the diff was quite appropriate.  You could make a patch via “git
 > format-patch” or “git send-email”, which would include a commit message
 > and which could include a move of sections 2.2 and 2.3 to the
 > contributing.texi.  But it is not necessary for documentation changes.

See attached.

 > >> > Matt matt <at> excalamus.com> writes:
 > >> > +You can install the Guix package management tool on top of an existing
 > >> > +GNU/Linux or GNU/Hurd system <at> footnote{Currently only the Linux-libre
 > >> > +kernel is fully supported. […]
 > >>
 > >> No.
 > >>
 > >> First of all, using guix-install.sh as per your instructions, one
 > >> installs the Guix distribution *and* package management tool.  Either
 > >> say “You can install the Guix package management tool and distribution”
 > >> or “You can install Guix”.
 > >
 > > I'm afraid I don't follow.  Where do you see the suggested changes
 > > confusing the installation process for Guix as a distribution and Guix
 > > as a package management tool?
 > >
 > > The sentence you quote is the suggested first sentence for the Chapter
 > > 2: Installation.  The complete sentence reads,
 > >
 > > "You can install the Guix package management tool on top of an
 > > existing GNU/Linux or GNU/Hurd system(1), referred to as a "foreign
 > > distro", or as a standalone operating system distribution, the "Guix
 > > System"."
 > >
 > > It literally says Guix is a package manager or a distribution.
 >
 > Precisely this terminology is the issue.  Nix is a package manager;
 > Nixpkgs is a distribution.  For Guix, Guix is both a package manager and
 > distribution.  Guix System is not a distribution in this sense; Guix is
 > the distribution.  I am aware that some people expect distribution to
 > mean a self-sufficient operating system, but we should not subscribe to
 > one side of terminology.  (Actually, the term operating system is
 > complex as well, for example GNU is an operating system and the people
 > from Robot Operating System call ROS an operating system.)

Thank you for your feedback.  Reading the suggested changes again with fresh eyes, I think I now see your concerns.  I see you raise two concerns:

1. A clear distinction between Guix and the Guix System was not made

I have split the suggested sentence, whose current version (v04) is given above, into two. One sentence has the subject of "the package management tool Guix" and the other "the Guix System".  You were correct in observing that the suggestion confused the meaning of "Guix".  Good catch!

2. The use of "operating system" is inappropriate

The v04 suggestion used "operating system" only because the current manual (bf53001) says in Section 1: Introduction, "If, instead, you want to install the complete GNU operating system..." before linking to "...how to install Guix System on a machine."

I have changed the patch set to say,

"If, instead, you want to install the complete, standalone GNU system distribution..."

This is based off the Section 1: Introduction which calls Guix System a distribution, "...or you can use [Guix] as a standalone operating system distribution, 'Guix System'" and Section 1.2: GNU Distribution which says, "we refer to the standalone distribution as Guix System."

I'm not sure if I've responded to all of your concerns here.  Have I missed any?

 > I would not address Hurd here at all.  Hurd support would be important
 > and is promising, but documentation for it should come after it works on
 > more than a Childhurd.

You say, "I would not address Hurd *here*" which implies it's valid to address Hurd elsewhere.  What's the criteria for deciding whether to address Hurd and how are the reasons I inadequate?

Here are the reasons I gave previously for why we should continue documenting Hurd support:

- The manual already documents Hurd support
- Core developers have published the statement, "running on the Hurd was always a goal for Guix"
- Guix can run on Hurd
- Code exists in the main branch for Hurd support

 > > No mention of 'guix-install.sh' is made on that page.
 >
 > I wanted to give an example what I mean, not a suggestion.

I don't understand what you mean then.  The exchange quoted here was part of the "Guix" versus "Guix System" discussion above.  Have the updates I've made there addressed this point?

 > >> Next, I believe Guix cannot currently be built on existing GNU/Hurd
 > >> systems, because guile-fibers does not work.  I do not really know
 > >> enough, but I would not mention Hurd support.
 > >
 > > The are two issues here, what is said and what should be said.
 > >
 > > Regarding what is said, the section we're talking about is for
 > > installing not building.  You *can* install the Guix package
 > > management tool on top of an existing GNU/Hurd system.
 >
 > Probably a guix pack of the guix package would run, but Debian’s
 > guile-fibers is not accepted, if I don’t misunderstand.

What I ask myself is, "Is this a problem or a detail?"  I know that probably sounds stupid.  However, the question is whether Guix can be installed on Hurd.  The answer is, Guix can be installed on Hurd.  Everything else, therefore, including guile-fibers or which Hurd, while important in other contexts, is not important to this issue.

 > > […]
 > >> >> Similarly, IMO the nuances are more appropriate in the old wording
 > >> >> “For Debian or a derivative such as Ubuntu,” rather than your change
 > >> >> “For Debian and Ubuntu-based systems”.
 > >> >
 > >> > The current wording is, "If you're running Debian or a derivative such
 > >> > as Ubuntu..."  None of the suggested changes include the wording you
 > >> > give.
 > >> >
 > >> > What are the nuances?  If they matter, we should probably make them explicit.
 > >>
 > >> The nuance is that Ubuntu is a derivative of Debian.  It can be
 > >> bootstrapped with Debian’s dpkg, although I did not follow a recent
 > >> e-mail thread on how to do this from a Guix-provided dpkg.
 > >
 > > Unless there's something about this nuance which directly affects the
 > > installation process, I don't think the distinction warrants mention.
 > >
 > > I opted to ignore the distinction and use "Debian and Ubuntu-based
 > > systems" because many popular distros, such as Ubuntu, Linux Mint,
 > > Zorin OS, Elementary OS, Linux Lite, and Pop!_OS, are known for being
 > > "based on Ubuntu."  The relevant information for users of these
 > > systems is not that they're derivatives of Debian, it's that this is
 > > the installation process for such systems.
 >
 > Ubuntu should not get the credits for what Debian is doing.  The current
 > wording “Debian or a derivative such as Ubuntu” is fairer and equally
 > clear.

Ensuring fairness is everyone's responsiblity.  I respect you for accepting this and speaking up.  I understand that you're concerned about proper attribution.

AFAIK, Ubuntu gives clear credit to Debian.  For example, the Ubuntu website says, "Debian is the rock on which Ubuntu is built."  https://ubuntu.com/community/governance/debian They give similarly clear statements elsewhere, too.

My understanding is that many distros call themselves "based on Ubuntu", "built upon Ubuntu", or list Ubuntu as "upstream" because they use packages that are, at minimum, distributed by Ubuntu.  That adds value also deserving of credit and which is separate from the value added by Debian.  Also, we must not overlook that Debian is itself built upon the work of others, many of whom are not associated with Debian and may not even be aware Debian packages or distributes their work.  This is all possible and just because of Free Software.  One of the four freedoms is the right to distribute unmodified copies.  It depends on the license terms, or lack thereof, whether explicit credit needs to be given.  I've not heard of Ubuntu violating any license terms or other legal restrictions requiring attribution.

Am I missing something?

 > >> Better not change the wording?  I believe enabling substitutes is not
 > >> the default.

You are correct!  I misunderstood the current manual and wrote that misunderstanding into my suggested changes.  I have updated the suggested changes.  Thank you for catching this!

 > I agree with you now that the wording can be simplified, except it must be rewritten to that disabling substitutes is an option that is not the default.

The term "substitute" is given in the Section 1 Introduction.  However, since it's jargon and this is a different chapter, I think it prudent to repeat the definition again as a reminder.

The 'guix-install.sh' script uses the term "pre-built package binaries" instead of "substitute":

"Permit downloading pre-built package binaries from the project's build farms? [Y/n]"

I propose the following.  The intent is to match the script's language so that readers may understand the consequences of a 'Y' or 'n' choice.  The best place to do this would be in the prompt.  However, documenting consequences in the manual seems a reasonable compromise which makes the prompt concise and allows us to link to the "On Trusting Binaries" section.

+By default, 'guix-install.sh' will configure Guix to download pre-built
+package binaries, called @dfn{substitutes} (@pxref{Substitutes}), from
+the project's build farms.  If you choose not to permit this, Guix will
+build @emph{everything} from source, making each installation and
+upgrade very expensive.  @xref{On Trusting Binaries} for a discussion of
+why you may want to build packages from source.

 > Otherwise LGTM.  Could you send another diff?

Gladly.  I reviewed our past messages and tried to document all the relevant changes in the commit messages.

[0001-doc-Simplify-installation-instructions.patch (application/octet-stream, attachment)]

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

From: "pelzflorian (Florian Pelz)" <pelzflorian <at> pelzflorian.de>
To: Matt <matt <at> excalamus.com>
Cc: 69977 <at> debbugs.gnu.org, Christian Miller <christian.miller <at> dadoes.de>
Subject: Re: [PATCH] doc: doc-Simplify installation instructions
Date: Mon, 25 Mar 2024 20:26:17 +0100

Hi Matt, mostly looks good to me.

Matt <matt <at> excalamus.com> writes:
>---- On Sat, 16 Mar 2024 15:05:13 +0100  pelzflorian (Florian Pelz)  wrote ---
>>>> Either
>>>> say “You can install the Guix package management tool and distribution”
>>>> or “You can install Guix”.
>>> You can install the Guix package management tool on top of an
>> Precisely this terminology is the issue.  Nix is a package manager;
>> Nixpkgs is a distribution.  For Guix, Guix is both a package manager and
>> distribution.[…]
> You can install the package management tool Guix on top of an

Looking at it with fresh eyes myself, your wording is OK.  Even though I
still think you have a misunderstanding of the term distribution, there
is no reason for me to insist the term distribution must be explained
here.


> 1. A clear distinction between Guix and the Guix System was not made
>
> I have split the suggested sentence, whose current version (v04) is
> given above, into two. One sentence has the subject of "the package
> management tool Guix" and the other "the Guix System".  You were
> correct in observing that the suggestion confused the meaning of
> "Guix".  Good catch!
>
> 2. The use of "operating system" is inappropriate
>
> The v04 suggestion used "operating system" only because the current
> manual (bf53001) says in Section 1: Introduction, "If, instead, you
> want to install the complete GNU operating system..." before linking
> to "...how to install Guix System on a machine."
>
> I have changed the patch set to say,
>
> "If, instead, you want to install the complete, standalone GNU system
> distribution..."

I like that you added the word “standalone”.  But I prefer the old
ordering where this sentence comes after “This section +is concerned
with the installation of Guix on a foreign distro.”


Looking at how to make an install tarball for Hurd, I noticed that you
removed these important instructions for building the tarball:

> -The binary installation tarball can be (re)produced and verified simply
> -by running the following command in the Guix source tree:
> -
> -@example
> -make guix-binary.@var{system}.tar.xz
> -@end example
> -
> -@noindent
> -...@: which, in turn, runs:
> -
> -@example
> -guix pack -s @var{system} --localstatedir \
> -  --profile-name=current-guix guix
> -@end example
> -
> -@xref{Invoking guix pack}, for more info on this handy tool.
> -
>  @node Requirements
>  @section Requirements

The tarball is needed by guix-install.sh, so the instructions for
building it should stay, because it is what your recommended
guix-install.sh uses.  Please keep the instructions for this reason.

No such tarball is released for GNU Hurd yet, and when I tried to build
it for GNU Hurd, it fails, because guile-git cannot be built.  Note that
it is possible to instead cross-compile a pack for Hurd, using
“--target=i586-pc-gnu” instead of “-s i586-gnu”, even though I have not
tested if it can be used.  Also note that Hurd is quite crashy.  Better
just not mention it here.



>> Ubuntu should not get the credits for what Debian is doing.  The current
>> wording “Debian or a derivative such as Ubuntu” is fairer and equally
>> clear.
> […]
> My understanding is that many distros call themselves "based on
> Ubuntu", "built upon Ubuntu", or list Ubuntu as "upstream" because
> they use packages that are, at minimum, distributed by Ubuntu.

I believe “Debian or a derivative such as Ubuntu” is a better wording
than “Debian and Ubuntu-based systems”, despite some Ubuntu derivatives
not mentioning Debian or users being aware only of Ubuntu.


> I propose the following.  The intent is to match the script's language
> so that readers may understand the consequences of a 'Y' or 'n'
> choice.  The best place to do this would be in the prompt.  However,
> documenting consequences in the manual seems a reasonable compromise
> which makes the prompt concise and allows us to link to the "On
> Trusting Binaries" section.
>
> +By default, 'guix-install.sh' will configure Guix to download pre-built
> +package binaries, called @dfn{substitutes} (@pxref{Substitutes}), from
> +the project's build farms.  If you choose not to permit this, Guix will
> +build @emph{everything} from source, making each installation and
> +upgrade very expensive.  @xref{On Trusting Binaries} for a discussion of
> +why you may want to build packages from source.

Good!


> * doc/guix.texi (Installation):
> - Move the definition of "foreign distro" out of quotation
> - Repeat overwrite warning
> - Remove superfluous commentary
> 
> * doc/guix.texi (Binary Installation):
> - Clarify that installing on a foreign distro has two methods: using
>   packaged binaries and building from source
> - Add cross reference to "Building from Git"
> - Move the foreign distro installation instructions out of quotation
> - Move directions for 'guix-install.sh' after instructions to use
>   distribution-specific package managers
> - Specify "distributions" as "GNU/Linux distributions"
> - Add GnuPG as a requirement for 'guix-install.sh'
> - Add comma after "Likewise"

I think this comma (“Likewise, on openSUSE:”) should not be added, since
it does not improve understanding, but it is not really important.


> - Remove redundant instructions to use 'guix-install.sh'
> - Split the requirements between system requirements for binary
>   installations, GNU/Linux or GNU/Hurd, and requirements for running
>   'guix-install.sh'
> - Clarify that 'guix-install.sh' guides users through the steps
> - Summarize the steps 'guix-install.sh' follows rather than try to
>   detail them
> - Make explicit that the 'guix-install.sh' default is to download
>   substitutes
> - Emphasize that the substitute authorization code is an example and
>   may need modification

Well these details are good for reviewers, but the commit message is
intended for readers of “git log”.  Better keep it short like the other
commits you can view with “cd ~/src/guix; git log doc”.

Could you send another patch without mentioning the Hurd, or do you see
a way to actually run Guix on a foreign GNU/Hurd distribution that you
can document?

Regards,
Florian

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

From: Matt <matt <at> excalamus.com>
To: "pelzflorian (Florian Pelz)" <pelzflorian <at> pelzflorian.de>
Cc: 69977 <69977 <at> debbugs.gnu.org>,
 Christian Miller <christian.miller <at> dadoes.de>
Subject: Re: [PATCH] doc: doc-Simplify installation instructions
Date: Sat, 06 Apr 2024 10:06:56 +0200

 ---- On Mon, 25 Mar 2024 20:26:17 +0100  pelzflorian (Florian Pelz)  wrote --- 
 > Hi Matt, mostly looks good to me.

That's good to hear!  I would like to address your comments in an updated patch set.  Unfortunately, I'm struggling to do that.  Between my last message and this one, life happened and changes have been made to guix.texi that prevent the application of patch set you've commented on.  I've already spent several hours already trying to figure out a better way to revise my suggestions than retyping everything by hand from HEAD.  How can git help me in this situation?  Or, am I better off scrapping my old patches and just retyping the changes?

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

From: "pelzflorian (Florian Pelz)" <pelzflorian <at> pelzflorian.de>
To: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
Cc: Josselin Poiret <dev <at> jpoiret.xyz>,
 Christian Miller <christian.miller <at> dadoes.de>, Matt <matt <at> excalamus.com>,
 69977-done <at> debbugs.gnu.org
Subject: Re: [PATCH] doc: doc-Simplify installation instructions (was Re:
 doc: installation: fix ~root confusion (was Re: doc: Removing much of
 Binary Installation))
Date: Sun, 07 Apr 2024 10:30:57 +0200

Thank you Maxim for the updating and pushing, so that future changes to
the install instructions will be based on Matt’s version.

Maxim Cournoyer <maxim.cournoyer <at> gmail.com> writes:
> Hi Matt et al.,
>
> Matt <matt <at> excalamus.com> writes:
>
>> Ugh.  All the patches were not attached to my previous message.  Here are all the patches.
>
> Excellent work.  Thanks for Florian and others for the comments.  I've
> now merged the 3 patches as-is, except for a trivial change to use @file
> to decorate 'guix-install.sh' in the first one.

I have followed up by:

commit 80d364b92b73e6757f2c9a703582519655bb4f5c (HEAD -> master)
Author: Florian Pelz <pelzflorian <at> pelzflorian.de>
Date:   Sun Apr 7 09:39:45 2024 +0200

    doc: Restore some of the old installation instructions.
    
    Follow-up to 227e0469dbfec7e47b57d824dcf45a04ac4026c9.
    
    * doc/guix.texi (Binary Installation):
    Revert wording for installing the Debian package.
    Restore how to reproduce the binary tarball.
    Restore how to uninstall.
    (copying): Add copyright notice for Matthew Trzcinski.
    
    Change-Id: Ib74199e39bd7a50ac58045f2bc47f61fc04eacb9

Regards,
Florian

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

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: "pelzflorian (Florian Pelz)" <pelzflorian <at> pelzflorian.de>
Cc: Josselin Poiret <dev <at> jpoiret.xyz>,
 Christian Miller <christian.miller <at> dadoes.de>, Matt <matt <at> excalamus.com>,
 69977-done <at> debbugs.gnu.org
Subject: Re: [PATCH] doc: doc-Simplify installation instructions (was Re: doc: installation: fix ~root confusion (was Re: doc: Removing much of Binary Installation))
Date: Tue, 09 Apr 2024 22:57:14 -0400

Hi,

Le 7 avril 2024 04:30:57 GMT-04:00, "pelzflorian (Florian Pelz)" <pelzflorian <at> pelzflorian.de> a écrit :
>Thank you Maxim for the updating and pushing, so that future changes to
>the install instructions will be based on Matt’s version.
>
>Maxim Cournoyer <maxim.cournoyer <at> gmail.com> writes:
>> Hi Matt et al.,
>>
>> Matt <matt <at> excalamus.com> writes:
>>
>>> Ugh.  All the patches were not attached to my previous message.  Here are all the patches.
>>
>> Excellent work.  Thanks for Florian and others for the comments.  I've
>> now merged the 3 patches as-is, except for a trivial change to use @file
>> to decorate 'guix-install.sh' in the first one.
>
>I have followed up by:
>
>commit 80d364b92b73e6757f2c9a703582519655bb4f5c (HEAD -> master)
>Author: Florian Pelz <pelzflorian <at> pelzflorian.de>
>Date:   Sun Apr 7 09:39:45 2024 +0200
>
>    doc: Restore some of the old installation instructions.
>    
>    Follow-up to 227e0469dbfec7e47b57d824dcf45a04ac4026c9.
>    
>    * doc/guix.texi (Binary Installation):
>    Revert wording for installing the Debian package.
>    Restore how to reproduce the binary tarball.
>    Restore how to uninstall.
>    (copying): Add copyright notice for Matthew Trzcinski.

 Sounds good; thank you for the follow-up!

Maxim

Previous Next

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