Standardize the Command Line Interface
Here are some recommendations after playing a bit with the CLI. In a nutshell, they aim toward following the usual practices of other well known CLI (git, apt, ...). In addition, nbgrader has a nice CLI and share much of the same aims as travo. Hence, being as compatible as possible is a good strategy.
-
Use verbs for actions (e.g.
travo create ...
,travo grant ...
, ...) -
Be explicit: reading aloud the command should give a clear idea of what it does
-
Use existing terminology whenever possible (e.g. gitlab's terminology)
-
Use options for named arguments
-
Use positional arguments for mandatory information and homogeneous collections (e.g. list of files)
-
No user interaction, except for requesting credentials, and possibly y/n confirmation for dangerous operations (with a -y option to bypass). If more information is required, suggest a new command to type to enter this information. For example, if there is an ambiguity when resolving the course, travo should list the options and suggest:
Use travo accept --course XXX
Rationale: its standard practice; it gives the user the full power of its shell (edition, completion, history, ...); it's easier to reuse in scripts.
-
Use URLs to identify resources (courses, groups, persons). These URL come for free with gitlab!
Note: numeric id's as identifiers are hard to remember, and break encapsulation by revealing internal information of gitlab's database. Use sparsely if at all in the CLI. Or only in operations that are meant to be automatized.
Examples
travo create https://gitlab.xxx/Info111/Assignements/Semaine1
The same, using a relative URL assuming the gitlab server URL is specified by the context (e.g. default value, environment variable, configuration file):
travo create Info111/Assignments/Semaine1
If the course itself specified by the context, this could boil down to:
travo create Semaine1
The following is ambiguous: this is granting access under which capacity?
travo grant Semaine1 Nicolas.Thiery
This is more explicit:
travo add_instructor Semaine1 Nicolas.Thiery
In my setup, I will use groups instead:
travo add Info111/Instructor Nicolas.Thiery
travo member Info111/Assignments/Semaine1 Info111/Instructor Developper
Submissions
For submitting, there are two possible choices. Either from within the directory:
travo submit file1, file2, ...
or nbgrader's style, from the parent directory
travo submit Semaine1
Do we really need file by file submission?
The above is assuming the course / assignment / ... info is available from the context or git repo. Otherwise this could be:
travo submit --assignment https://gitlab..../Semaine1 ...