One of the most underappreciated professions is that of the Technical Writer. These are the amazing people that generate the documentation that comes along with high quality software. They’re also, as writers tend to be, eagle eyed for inconsistencies in the design of textual interfaces.
I have the fortune of knowing a handful of technical writers, and recently I received some feedback on NetAuth that the CLI tools have inconsistent interfaces. Some things are plural, some things are case sensitive, some things aren’t, and some things can fail in obscure ways if you don’t specify exactly the right combination of attributes.
This is unacceptable.
Clearly then the solution is a fix-it release that will break certain interface assumptions and fix these things. Fixing things though requires some agreement on the end state. Therefore, it is being laid down here for how the CLI interfaces will change. The RPC interfaces will remain stable, as those are reasonably consistent, but the CLI interface shall be cleaned up.
Entities and Groups
Initially, the intent has been that entities had IDs and groups had
Names. This is carried through the code internally and is a nice
distinction to make there, but the way most people speak about things
is to say “entity foo” or “group bar” which makes sense to reflect in
the tooling. Thus, across all CLI tools the flags shall be --entity
and --group to specify an entity and a group. This is slightly more
characters to type, but it is clearer as to what the flag is for.
Multi-Mode Options
Currently, there are a handful of commands that take options of the
form --mode <mode> or --action <action>. Take for example the
mode selector that is on the group expansion command. It has options
INCLUDE, EXCLUDE, and DROP. These options will become separate
flags: --INCLUDE, --EXCLUDE, and --DROP, with appropriate
interlocking checks.
Case in Option Parameters
This one is easy, all parameters that are fed into commands for purposes of field printing shall be case insensitive.
Command Naming
This is one that should have never been an issue, yet if you look at the output of the commands help screen (abridged):
Subcommands for Entity Administration:
new-entity Add a new entity to the server
remove-entity Add a remove entity to the server
Subcommands for Group Administration:
new-group Add a new group to the server
delete-group Delete a group existing on the server.
There’s agreement that new should be for adding things, but not how to remove them. Both of these shall be changed to match the naming elsewhere in the system, the verb ‘create’ shall be used for additive state changes, and the word ‘destroy’ shall be used for destructive state changes.
>> Home