Subject: Re: The usability of Guix configurations

From: Leo Famulari <[email-masked]>
Date: Mon, 6 Nov 2017 17:16:21 -0500

On Mon, Nov 06, 2017 at 03:12:11PM -0500, myglc2 wrote:
> My system recently broke when I did an upgrade. I reported what I
> thought was a bug (bug#29072) but it turned out that, because qemu
> package code had been moved, my system configuration had become broken
> ;-(
> 
> Confronted with my situation, helpful developers said "The package code
> was moved in commit xxx" (Leo) and "maybe you have a mistake in your
> config (Efraim)."

I'm sorry that my comment was not enough on its own!

> Once I understood what had happened I wondered, "Gee, I have been using
> guix for 18 months so why didn't I figure this out myself." ;-)
> 
> But a less committed user might say, "Wow, Guix breaks at random, error
> messages are hard to understand, and support is difficult."  :-(

Good point.

> ISTM this raises issues and questions about Guix configuration
> usability:

Indeed.

> Guix config errors are reported as raw scheme errors which are not
> user-friendly, except, perhaps, to guile users ;-) Could we improve this
> situation by adding config troubleshooting guidance to the doc?

Yes, we do try to add helpful error messages, although obviously there
is a lot more work to be done.

As far as I can tell, the issue was related to the fact that you are
using Guix by building it from source and re-using the same build
directory, which may contain stale compiled .go files. In this case,
there was a leftover qemu.go, which shadowed the correct file,
virtualization.go.

This is a useful development technique but not how Guix is supposed to
be deployed and updated. `guix pull && guix package --upgrade` is still
what we recommend and support.

If you want to deploy Guix by building it "by hand", I recommend using a
fresh Git checkout and directory each time you build it. That way, you
can be sure to avoid this class of error (stale module references in
leftover .go files), which is well-known to the seasoned Guix developers
but totally confounding for everyone else.

> Guix config errors consume meaningful amounts of user and support
> effort. I say this because a) it took quite a few iterations to figure
> out what was wrong in my situation, and b) google search for '"no code
> for module" guix' finds 613 hits, which will no doubt grow linearly with
> number of Guix users unless something is done. So I wonder, could an
> error handler that translates into more user-friendly terms reduce user
> frustration, increase the rate of user self help, reduce support load,
> and effectively pay for itself?

That would be awesome!

> Are the current Guix config errors usable by the average GNU/Linux
> distribution user? If not, don't they need to be improved before we call
> it 1.0?

Based on how much time it's possible to spend on IRC helping people, I'd
say there is lots of room for improvement in this area.

> Does this mean that package code must not be moved after 1.0?

A couple thoughts... it would be nice if the GuixSD configuration
example templates used a filename agnostic method of resolving module
imports. I'm not a strong enough Schemer to evaluate the situation or
suggest a solution, but I think that the filenames should not be
relevant at that level. Perhaps one could use
'specification->package+output',
as demonstrated in the documentation of package manifests:

https://www.gnu.org/software/guix/manual/html_node/Invoking-guix-package.html

> Finally: Should I close bug#29072? ;-)

The problem of the missing QEMU patch is resolved. The broader issue of
confusing error messages could be continued here, or elsewhere. It's up
to you :)