[PATCH 00 of 17 v3] Introduction of kallithea-cli command

[Mads Kiilerich]

On 10/18/2018 10:49 PM, Thomas De Schampheleire wrote:
> This series introduces a kallithea-cli command to replace our custom gearbox
> commands.
> At the end of this series, the help text will show:
>
>
> Usage: kallithea-cli [OPTIONS] COMMAND [ARGS]...
>
>    Various commands to set up a Kallithea instance.
>
> Options:
>    --help  Show this message and exit.
>
> Commands:
>    cache-cleanup-keys  Clean up existing cache keys.
>    cache-show-keys     Show existing cache keys with their status.

These two commands are really not so much about some kind of "keys". 
They are about database entries that indicate that some worker process 
has a repo cached in memory, so the cache can be invalidated and flushed 
when necessary. It would thus perhaps be better to name these commands 
so they are grouped with other repo commands, like:

repo-cache-cleanup   Flush in-memory repository caches.
repo-cache-show    Show current in-memory repository caches.

>    celery-run          Start Celery worker(s) for asynchronous tasks.
>    config-create       Create a new configuration file.
>    db-create           Initialize the database.
>    extensions-create   Write template file for extending Kallithea in Python.
>    front-end-create    Create the front-end.

The "create" naming consistency is generally nice, but for this one, 
"build" seems much more descriptive and correct.

>    iis-install         Install into IIS using isapi-wsgi.
>    index-create        Create or update full text search index
>    ishell-run          Interactive shell for Kallithea.
>    repo-purge-deleted  Purge backups of deleted repositories.
>    repo-scan           Scan filesystem for repositories.
>    repo-update-cache   Update repo cache after external modification.

This one is perhaps better described as: Update database cache of latest 
repository change.

> Some notes:
> - In v1 and v2, each topic was a separate word in the CLI, e.g. 'repo
>    update-cache' rather than 'repo-update-cache'. There were two problems
>    with that approach:
>    1. to know which commands are available, you'd use 'kallithea-cli --help'
>       to discover the topics, then 'kallithea-cli topic --help', and then
>       you'd still need another 'kallithea-cli topic command --help' to
>       get a list of the actual options.

Hmm. I see. Good point. Annoying how it seems to force us to use a 
not-so-elegant solution with the "object" and the "method" tied together 
in the command name. But it also gives a more flat namespace that is 
more explorable ...

In a way, it could perhaps be more elegant with more specific top level 
command names, something like
   kallithea-repo update-cache my.ini foorepo barrepo
but that would have some of the same problems ... and perhaps give too 
many commands, which might be a problem or a solution ...

Also related to that: when thinking about a consistent solution, we 
should perhaps also consider where the existing kallithea_api.py 
kallithea_backup.py  kallithea_gist.py could fit in.

>    2. some command-lines would become quite long, and distinction between
>    elements of the command itself, and its arguments, were hard to see. For
>    example, to update repository caches:
>       kallithea-cli repo update-cache my.ini foorepo barrepo
>       vs.
>       kallithea-cli repo-update-cache my.ini foorepo barrepo

Also, looking at the examples (both commands in this patch series an 
examples from other tools), it seems less elegant when commands have 
different "positional parameters", like how parameter 1 is the .ini file 
and parameter 2 and up are repository names. I kind of like how the 
gearbox solution consistently use -c for these config files. The general 
rule for command line design might be that un-named parameters only 
should be used to name the main things we operate on.

> - We need to find a better place for template.ini.mako which is now the sole
>    inhabitant of kallithea/lib/paster_commands/.

kallithea/templates/ is mostly html templates for the front-end, but we 
also have kallithea/templates/email_templates/ , so perhaps this one 
could be placed as something like kallithea/templates/config.ini .


soooo ...


With these nice experiments and overviews, it is interesting to take a 
step back and look at them and other complex and more or less elegant 
commands with sub-commands. Here are some I know about:
https://docs.docker.com/engine/reference/commandline/cli/ 
https://docs.docker.com/engine/reference/commandline/docker/
https://docs.ansible.com/ansible/2.4/command_line_tools.html
https://dnf.readthedocs.io/en/latest/command_ref.html
https://linux.die.net/man/1/fedpkg
https://www.mercurial-scm.org/doc/hg.1.html
http://man7.org/linux/man-pages/man1/git.1.html
https://www.openssl.org/docs/man1.1.1/man1/openssl.html

One thing I conclude is that it indeed only is common to use one level 
of sub commands. But it varies whether sub-sub commands are implemented 
by having verbose sub command names (seems quite common for example in 
git) or using additional flags and having other options that only works 
together with some flags (for example like openssl or hg). I agree with 
the longer sub-command names without nesting here in v3.

I do however think that the config file as first unnamed parameter was 
another thing that contribute equally much to the hard-to-read commands 
from v2. That remains. What are your thoughts about re-introducing -c as 
a (mandatory) parameter?

Another observation from looking for examples, is a concern whether my 
preference for "kallithea-cli" over just "kallithea" is justified. I 
would still say a vague "yes", but I am less confident. (For the 
examples I listed above, the command line tool comes closer to being the 
tool itself. For Kallithea, the tool is only for admin stuff - it is not 
Kalllithea itself.)

/Mads