(name . guix-patches)(address . guix-patches@gnu.org)
18e6fc95976.1123b38ca424631.8698364288744551259@excalamus.com
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@excalamus.com> writes:
> >> > +You can install the Guix package management tool on top of an existing
> >> > +GNU/Linux or GNU/Hurd system@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/debianThey 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.