Re: Reorganizing guix package commands

[myglc2 <myglc2@gmail.com>]

ludo@gnu.org (Ludovic Courtès) writes:

> Alex Kost <alezost@gmail.com> skribis:
>
>> I've just sent a message to bug#22587¹, but I realized it is better to
>> discuss it here in a separate thread.
>>
>> So, I think there are inconsistencies in guix commands.  For example, we
>> have "guix system build" to build a system, but "guix build" to build a
>> package.  IMO "guix package build" would be a better choice.
>>
>> In general, I think it would be good to move package commands inside
>> "guix package", e.g, to make "guix package lint", "guix package size",
>> etc.
>
> Why not consider “package” to be the default word?  :-)
> I can see how adding “package” everywhere helps categorize things
> mentally, but as a user interface, I think it would be rather bad.
>
> Also, it’s not that simple: “guix size” can take a store item instead of
> a package name, “guix graph” cannot do it yet but it would be useful if
> it could (“guix graph -t references $(readlink -f /run/current-system)”),
> etc.
>
> I still think that having aliases like “guix install” as Andy proposed
> long ago would be useful, though I never started working on it.
>
> There are probably other improvements to do around “guix package” (maybe
> turning some of its options into separate sub-commands as was suggested
> before.)  All we need is a clear view of where we’re going and patches.  :-)
>

I replied to the bug earlier, relevant parts are restated below, and a
discussion added below that.

For overall Guix usability, the overloading of a single guix command for
everything is not so good. When you eventually create a man page, it
will be intimidating for someone just trying to do per-user package
management, which the majority of, and least sophisticated users, will
be trying to do.

On the other hand there are several "classes" of commands as reflected
by the guix CLI being described in several logically different parts of
the doc. This structure is not so evident in the CLI structure.

A possibly better approach would be to explicitly split the guix
command-verse into command classes to better match the structure of the
doc and/or the class of the user. For example, per-user ('guix ...'),
global-system ('guix-sys ...'), and developer ('guix-dev ...'), or
something similar.

Since the most frequently used commands will be per-user package
management, I suggest you replace 'guix package' with 'guix' and promote
the non-package commands to be hyphenated (ALA guix-daemon).

This would, in turn, give rise to emacs functions something like:

OLD                                    NEW
-------------------------------------------------------------------
user:
guix-edit                              guix-view-definition
guix-installed-packages                guix-installed-packages
guix-installed-user-packages           NA

admin:
guix-installed-system-packages         guix-sys-installed-packages

developer:
guix-hydra-build-list-latest-builds    guix-dev-hydra-build-list-latest-builds
guix-edit                              guix-dev-edit-definition

While this would be not-so-nice for a power emacs user, it would make it
easier for a less experienced user to find a relevant command in the sea
of 'M-x guix-' commands in the *Completions* buffer.  This kind of
naming may not be typical in emacs, but I think it is probably justified
considering the range of disparate functions provided by Guix, as
discussed below.

***

Regarding the bigger picture, and sorry this is so long, thinking more
deeply about the situation, IMO, Guix usability challenges stem mostly
from the fact that Guix provides an unexpectedly large range of
functions: a per-user package manager, an OS, a system configuration
tool, a packaging tool, a package editor, an installer, VM managers,
developer utilities, hydra managers, and maybe some other things ;)

Further, Guix behavior is modal, e.g., which functions work depend on
how Guix was installed and/or configured. For example, in a Guix/Debian
install, 'guix system reconfigure config.scm' churns away happily for 15
minutes and then produces the error, 'guix system: error: symlink:
Permission denied: "/var/guix/profiles/system-1-link"'

OTOH, other things you might not expect to work actually do, e.g.  "guix
init ..."  will "upgrade" your Debian OS install to GuixSD ;)

So, the problem goes well beyond function names. The underlying problem
is that grouping such a large and disparate set of functions together in
a single package is counter-intuitive. And further accessing them all
under a single CLI/UI is challenging, to say the least.

As a result, Guix is difficult to document and understand.  The low user
list activity is evidence that many potential users find the www doc
intimidating and bail out before downloading. This may actually be OK
since you are probably not ready for them anyhow.

But users that do get as far as installing are confronted by 8 guix INFO
entry points and 120+ "M-x guix-" functions.  The only users that can be
expected to work this way are Guix developers or, perhaps, hardened
emacs criminals ;-) Others have trouble finding the relevant entry
point, e.g,

http://lists.gnu.org/archive/html/help-guix/2016-04/msg00056.html

To summarize, Guix has a lot of functionality and complexity. So to be
successful, we must consider carefully how to package and describe it.

One way would be to split guix into ~three pieces.  We could do this by
clearly identifying the classes of users we expect to serve and then
splitting out functions by user class.  Something like sysadmin,
end-user, and developer. This would probably be the simplest solution
(for users, that is), but I imagine we don't want this.

Alternatively, if we continue on the current path, we need to describe
the new software paradigm that motivates placing these disparate
functions together.  We need to explain how the functions fit
together. And we need to provide a map that helps each class of new user
to find their way in.

A while ago I took a crack at this:

http://lists.gnu.org/archive/html/guix-devel/2016-03/msg00674.html

http://lists.gnu.org/archive/html/guix-devel/2016-03/pngM78VCHVVDp.png

And it probably needs more work along the lines of explaining and
motivating the paradigm. Ludo used a couple of ideas in this commit:

http://lists.gnu.org/archive/html/guix-devel/2016-03/msg01038.html

But I think we should revisit the original objective, which is to
provide a brief illustrated Guix overview as an entry to all of
Guix.

Ideally this would provide a reference point in thinking about the
questions raised above. - George