define conventions for kolibri commands

[indirectlylit]

Observed behavior

Let's decide on conventions for manage commands.

Two recent examples:

• https://github.com/learningequality/kolibri/pull/3594#issuecomment-388210709
• https://github.com/learningequality/kolibri/pull/3619#pullrequestreview-119193589

Other inconsistencies:

• shell
• plugin
• some older commands

Expected behavior

commands are consistent

User-facing consequences

not too much at the moment, but longer-term we want a clean command-line UI

[indirectlylit]

In #3594 we decided to use the command

kolibri manage content movedirectory

At the risk of bike-shedding that decision, I wanted to propose one convention update before committing to it:

Multi-word commands should be snake_case.

In this case, the command would become kolibri manage content move_directory

Mashing multiple words together without any clear separator makes them hard to read, which is especially problematic because we won't be internationalizing the commands any time soon.

(In this case, the command scans to me like "moved irectory")

[lyw07]

I agree that move_directory sounds more clear. I will make changes to the command name.

[benjaoming]

Multi-word commands should be snake_case.

Where is the quote from @indirectlylit ? IIRC, most django management commands are without underscores or dashes, like makemigrations.

[rtibbles]

Yeah, it is definitely more djangoic to not underscore.

[rtibbles]

I believe that the quote is from himself, @benjaoming.

[indirectlylit]

Yes, it wasn't a quote - it was a proposal .. Note that I also updated the issue title from "kolibri manage commands" to "kolibri commands".

Agreed that we should not violate conventions if possible. However we should also give Kolibri users the best possible experience, irrespective of Django conventions they likely won't be aware of.

Perhaps we need to treat the manage subcommands as an advanced implementation detail and proxy to them. E.g.

kolibri content move-directory

could proxy to

kolibri manage content movedirectory

This would allow all user-facing commands to have a short, clean form (like start and language).

Note that GNU recommends dashes between words:

Option names are typically one to three words long, with hyphens to separate words. Users can abbreviate the option names as long as the abbreviations are unique.

[benjaoming]

Sorry, I can't chime in with any bias or intuition or preference here. I like kolibri content move_directory or kolibri content move-directory for readability. I like Django-ish conventions, too.

I'm +0 for both :)

[benjaoming]

...but I don't like the proxy or alias'ing stuff, it will have to end up in documentation, and that will make it cluttered.

[benjaoming]

Maybe I slightly prefer the Django-way, because I know that in 6 months, I won't be wondering if it had an underscore or not :)

[benjaoming]

But only very very very slightly