bug#29072: The usability of Guix configurations

bug#29072: The usability of Guix configurations

[myglc2]

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)."

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."  :-(

ISTM this raises issues and questions about Guix configuration
usability:

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?

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?

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?
        
Does this mean that package code must not be moved after 1.0?

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

bug#29072: The usability of Guix configurations

[Leo Famulari]

[-- Attachment #1: Type: text/plain, Size: 3671 bytes --]

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 :)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

bug#29072: The usability of Guix configurations

[myglc2]

Please note: these replies separated by topics in an effort to make the
threads more topical ...

On 11/06/2017 at 22:16 Leo Famulari writes:

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

Hey Leo,

Please understand that don't mean this as a complaint your reply, which
was helpful and I was very happy to receive.

I am just trying to step back and think about the bigger picture.

bug#29072: The usability of Guix configurations

[myglc2]

Please note: these replies are separated by topics in an effort to make the
threads more topical ...

On 11/06/2017 at 17:16 Leo Famulari writes:

> On Mon, Nov 06, 2017 at 03:12:11PM -0500, myglc2 wrote:
[...]
>> 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.

I didn't mean this point critically. Rather as a statement of fact. When
I said ...

>> Could we improve this situation by adding config troubleshooting
>> guidance to the doc?

... I was thinking something like ...

vvvvvvvvvvvvvvvvvv

Troubleshooting your config file:

If you get an error like:

ice-9/boot-9.scm:[...] no code for module (gnu packages <package name>)

You have either specified a package name that does not exist, or your
(use-package-modules <package module names>) does not contain the name
of a package module that contains the definition of <package name>.

You can determine which, if any, module contains a package definition by
yada yada yada

^^^^^^^^^^^^^^^^^^

... thinking that then there would be a search hit in the doc for 'no
code for module' which might enable some users to understand what they
are doing wrong.

WDYT? - George

bug#29072: The usability of Guix configurations

[myglc2]

On 11/06/2017 at 17:16 Leo Famulari writes:

> 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.
[...]
>
>> 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
>
There is a parallel solution 
>> 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 :)

bug#29072: The usability of Guix configurations

[Ludovic Courtès]

Hello,

myglc2 <myglc2@gmail.com> skribis:

> 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
> ;-(

It should be noted that you were using a “developer setup”, specifically
running Guix from a checkout with ./pre-inst-env and all.

The issue with the stale module wouldn’t happen with “guix pull”, which
is the recommended “user setup.”

While I agree the situation is not ideal, I think we have to admit that
developers can always shoot themselves in the foot, and that was one way
of doing it.  ;-)

Thoughts?

Ludo’.