bug#53224: Cookbook recipe about profile collisions

[Leo Famulari <leo@famulari.name>]

On Fri, Jan 14, 2022 at 09:47:52AM +0100, Ludovic Courtès wrote:
> > 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?

I pointed to this blog post, which was linked from that email:

> > Specifically see this blog post:
> > http://excalamus.com/2021-10-06-guix-debug.html

It's the story of an attempt to learn what the "conflicting entries"
message means and how to resolve it.

> 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?

The hint is perfectly clear, when you understand "profiles" and
"propagation".

It's like I said later in my message: People use Guix without knowing
very much about it.

That's surprising to me, because I started using Guix *because* I
learned about profiles and how they are used: it's one of the core
innovations of Guix / Nix, to implement unprivileged package management.

But nevertheless, people are using Guix without understanding how it
works. And it's hard to learn about Guix when you are dealing with a
profile collision that you don't understand at all. For many people,
that is not a good moment to start learning. On top of that, profile
collisions are an error state that we can't fix as a bug: we have to
give users the knowledge to resolve the collisions themselves.

For example, the blog post that I linked to ends with "Lessons Learned",
which includes this:

------
What is a profile?

A profile is a directory of symlinks located at ~/.guix-profile.

Propagated inputs can cause conflicts

Propagated inputs are treated somehow differently. It's still not 100%
clear how or why, but it's good to know they're a potential source of
errors.
------

This person spent a lot of time trying to understand the situation and
writing the blog post, but their understanding is still rather weak.

That's why I propose a Cookbook chapter that specifically addresses
profile collisions, to help new users go from "oh no, an error message"
to "aha!"

> 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?

I think this part of the manual is fine and can stay as it is.

> 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?

The illustrations of the symlink forest were *extremely* helpful to me
when learning how Guix implements unprivileged package management. I
think that later talks from the 2015-2017 era refined the illustrations
to be even more clear.

I'm sorry if the use case for my proposal is still unclear. I can work
on the Cookbook chapter myself.