There are several actions which we have deferred and other topics which still need to be addressed, such as those raised by Vagrant and Suhail. My hope is to 1) resolve and merge this immediate patch, as we appear to be converging on a consensus, 2) discuss how we could better handle documentation changes than how I've handled them here (that is, in one ever evolving diff), 3) compile a list of deferred actions, 4) compile a list of deferred topics, and 5) address points 3 and 4 according to 2. ---- On Mon, 11 Mar 2024 16:54:01 +0100 pelzflorian (Florian Pelz) wrote --- > Hi Matt. I would almost want to push your changes, but we still > disagree on some wordings. I'm glad to hear the suggested changes are more acceptable than not. Let's do what we need to get things right. > Yes, however the removal means that we should move the sections > > * 2.2 Requirements > * 2.3 Running the Test Suite > > to the Contributing manual in doc/contributing.texi. WDYT? You said, > it could be a separate discussion, but in my opinion it would be part of > the same patch. I was thinking of the opposite, of moving "Building from Git" into Installation. What you say makes more sense and I agree. Since the suggested patch is already quite complex, I have not added moving Sections 2.2 and 2.3 to the changes. I propose we make the move in a separate commit. > > +@cindex foreign distro > > +@cindex Guix System > > “@cindex Guix System” is inappropriate, because instructions on Guix > System are not here. Removed. Good catch! > > +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. No mention of 'guix-install.sh' is made on that page. The current "introduction" to Chapter 2: Installation is this: "Note: We recommend the use of this to install Guix on top of a running GNU/Linux system, thereafter called a foreign distro. The script automates the download, installation, and initial configuration of Guix. It should be run as the root user." https://guix.gnu.org/en/manual/devel/en/html_node/Installation.html Maybe the diff didn't apply correctly? Maybe it's confusing how the Texinfo syntax puts the footnote markup in the middle of the source sentence, even though footnotes render at the bottom of the page? > 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. This is exactly what the suggested changes say, minus the emphasis. As far as I know, it's true: 1. https://guix.gnu.org/en/blog/2020/a-hello-world-virtual-machine-running-the-hurd/ 2. https://guix.gnu.org/en/blog/2020/childhurds-and-substitutes/ Further, the manual already mentions Hurd support: https://guix.gnu.org/en/manual/devel/en/html_node/operating_002dsystem-Reference.html Beyond the manual, there are two blog posts (linked above) which have explicit sections about why it makes sense to develop for Hurd. Code for Hurd is mainlined with 80 files in the master branch providing Hurd support. I get it, it's the Hurd. Running Guix on Hurd was part of a joke. Correct me if I'm wrong, though: Hurd support wasn't the punchline, ending support for Linux was. The part that said, "running on the Hurd was always a goal for Guix" is sincere. So, what should be said is that Hurd support is limited. Any errors are bugs, either for Guix or for upstream. I've updated the footnote to warn that Hurd support is currently limited. > Additionally “only the Linux-libre kernel” is incorrect, because > running Guix on non-libre Linux is fully supported. Running Guix > System there is not supported (by us). Excellent point: the package manager is indeed supported on non-free distros. I had carelessly copied the footnote, and the text containing this issue, from another section. The update on the previous point, regarding Hurd support, removes this issue by removing mention of Linux. > >> Therefore, the sentence would have to be removed: “The following > >> sections describe two methods of installation, binary installation > >> and building from source.” > > > > I've removed that sentence for a different reason. I also revised the > > sentence, "This is often quicker than installing from source, which is > > described in the next sections", to simply, "described later". > > > > The reason is that Chapter 2 doesn't currently explain building or > > installing from source. Building and installing from source is > > currently covered much later in Section 22.1. Whether or not the > > Installation section should cover building from source is a separate > > issue and shouldn't be part of this discussion. > > This could be: > > described later (@pxref{Building from Git}). Updated. > >> Matt matt@excalamus.com> writes: > >> > - Add commas in appropriate places; after "For...Ubuntu-based > >> > systems", "Likewise", and the 'or' within the list of substitutes > >> > >> I’m not a native speaker, but I believe the commas are not > >> necessary. There particularly does not need to be an Oxford comma > >> before ‘or’. There could be, but there is no reason to change it. > > > > Ah, the One True Brace Style of natural language :) > > > > I think there's already enough controversy in this thread. I've changed it back :) > > :D However, please also do not change: > > > -Likewise on openSUSE: > > +Likewise, on openSUSE: Corrected. > >> 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. > > +@quotation Note > > +By default, binary installations of Guix build @emph{everything} from > > +source. This makes each installation and upgrade very expensive. > > +@xref{On Trusting Binaries} for a discussion of why this is the default. > > […] > > - > > -@quotation Note > > -If you do not enable substitutes, Guix will end up building > > -@emph{everything} from source on your machine, making each installation > > -and upgrade very expensive. @xref{On Trusting Binaries}, for a > > -discussion of reasons why one might want do disable substitutes. > > @end quotation > > Better not change the wording? I believe enabling substitutes is not > the default. My assumption is that the vast majority of readers are not installing Guix on distros whose default is to compile from source. The concept and jargon of substitutes, let alone the idea of compiling from source, is likely completely unknown to most readers. Readers likely expect, what we would call, substitutes to be enabled. As far as I understand, the default behavior is opposite what most readers would expect: substitutes are *not* enabled by default for binary installations of Guix. The suggested wording avoids the jargon of "substitutes" in favor of simpler language which directly addresses what the reader likely cares about: the default Guix behavior is to compile from source which takes a long time. It also frames the discussion of "On Trusting Binaries" from the perspective of "the expensive default was decided by careful consideration." The current wording, "why one might want to disable substitutes," involves jargon (substitutes) and a negative (disable) which requires understanding what a substitute is, what the default is, and whether "disabling" is contrary to the default. That complexity is unnecessary, as I believe the suggested changes demonstrate. I think a valid critique of the suggested changes is "why say 'very expensive' instead of 'takes a long time'?" The suggestion uses the phrase "very expensive" instead of "takes a long time" because 1) "very expensive" is the current language and 2) wall time is only one of several expenses; others are energy and CPU cycles. This is a situation where I think it's okay to be non-specific. The point is "the default behavior may seem undesirable" and the word "expensive" is typically considered undesirable. > IMHO The discussion about whether Upgrading Guix should recommend to > edit the systemd service of the Debian guix package is for a > separate second patch. Agreed.