Subject: bug#53224: Cookbook recipe about profile collisions

From: Leo Famulari <[email-masked]>
Date: Wed, 12 Jan 2022 19:11:59 -0500

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

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.

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.