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
_______________________________________________
kallithea-general mailing list
kallithea-general@sfconservancy.org
https://lists.sfconservancy.org/mailman/listinfo/kallithea-general
