bug#53224: Cookbook recipe about profile collisions

["Ludovic Courtès" <ludo@gnu.org>]

Hi,

Leo Famulari <leo@famulari.name> skribis:

> Recently, Matt pointed out that profile collisions can be confusing and
> difficult to resolve:
>
> https://lists.gnu.org/archive/html/guix-devel/2022-01/msg00115.html

I don’t see the words “profile” and “collision” here; maybe that was
upthread?

> Specifically see this blog post:
> http://excalamus.com/2021-10-06-guix-debug.html
>
> I think we should add a Cookbook chapter on the subject.
>
> This particular error state seems unavoidable given the size of the
> distro and the number of packages that use propagation.
>
> So, let's help users understand it and give them the knowledge to even
> help resolve such collisions as contributors.
>
> Speaking as somebody who understands intimately what a profile is, what
> propagated inputs are, and how they can interact to cause "profile
> contains conflicting entries", I am sympathetic.
>
> Although I know exactly how to resolve such errors, I have also
> explained the situation to new Guix users several times on IRC.

Yeah, we need to get a good understanding of when that happens, and
what’s confusing.

Currently, on profile collisions, the error message shows where the
collision originates and a hint on how to work around it.  Perhaps the
hint is sometimes wrong (in which cases?), or perhaps it’s too terse?
Can it be improved?

> Many people come to Guix, install some packages, use them, then want to
> upgrade them, and they have never learned what a profile is or how it is
> the fundamental mechanism by which Guix implements package management.
>
> It also seems to me that plenty of people would prefer not to ask for
> help, but rather go searching online and in the documentation, which
> does not include the string "contains conflicting entries".
>
> I envision a Cookbook chapter that explains what a profile is, what
> propagation does, what profile generations are, and then how they all
> combine to cause this error state. And an example of a resolution,
> whether by adjusting a package definition, uninstalling a package, etc.
>
> There are some older Guix presentation videos that I think do a great
> job of explaining profiles and generations, including slides with good
> illustrations of the subject. It would be nice to try using that style
> of illustration, as I found it clear and illuminating when I first
> learned about Guix.

The definition of what a profile is is another topic.  Currently the
term “profile” is defined in “Getting Started”:

  https://guix.gnu.org/manual/en/html_node/Getting-Started.html#index-profile

It’s very much defined in passing though.  How can we improve on that?

In some early talks we had illustrations of the symlink forest of a
profile borrowed from Eelco Dolstra’s own talks on the matter; see for
instance p. 17 of <https://guix.gnu.org/guix-fosdem-20140201.pdf>.  I
stopped using it because I think those symlinks are an implementation
detail and it doesn’t help to focus on symlinks (and hashes and all
that) when giving an overview of the tool.  Now, perhaps that
illustration could be useful in the manual.

WDYT?

Thanks,
Ludo’.