aurora-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Toby Weingartner <tweingart...@twitter.com>
Subject Re: Adding shorthands, defaults, and initialization files to the aurora client
Date Mon, 19 May 2014 17:01:30 GMT
Comments inline.


On Mon, May 19, 2014 at 8:44 AM, Mark Chu-Carroll <mchucarroll@apache.org>wrote:

>
> A proposal for how to do this is below. Comments are not just welcome but
> required!
>

Ok, required it shall be.


## Standard Shortcuts
>
> To save typing, we'll add _automatic_ shorthand generation to
> the command-line framework. For nouns and verbs, any unambiguous
> prefix of the appropriate word will be automatically expanded to
> the full word.
>
>    * `aurora j c` will be expanded to `aurora job create`.
>    * `aurora con l` will be expanded to `aurora config list`.
>

Would it make sense to have an "alias" function, similar to what git has,
where the commands following the "aurora" command may be aliases, that get
expanded, instead of this implicit shorthand generation?

While I see this shorthand generation easy to do, and easy for people to
reason about, I also see it as being a problem in the sense that to have a
portable script use the tool, it will always require the commands be
spelled out in full (which I may argue is a good thing in a script) in
order to future proof itself.

The problem with humans (as I see it), is not just a propensity to be lazy,
but also a reluctance to change.  In other words, if "aurora j c" works for
them today to create a job, they'll be upset if "aurora j c" is not
un-ambiguous in the future due to the creation of a new noun/verb that
conflicts, necessitating either creative noun/verb choices, or having
people change their typing habits.

The ability to have aliases, almost completely obviates that.  There are
down sides to this option as well, of course.



> ## User Customizations
>
> To allow users to customize shorthands, we'll provide a
> builtin capability to allow users to provide a configuration
> file, from which their customizations will be loaded.
> Many applications use a simple pattern to solve similar problems.
> Vagrant uses a file named "Vagrantfile"; when you run vagrant, if you
> don't specifically tell the tool where to find a configuration, it looks
> in the current directory or one of its parents to find a file named
> "Vagrantfile".
>
> We'd like to follow a similar pattern, and create an "AuroraInit" file.
>

We should standardize the filename(s), capitalization(s), and locations at
this point. I realize we may break backwards compatibility completely, but
that's better to do now, than later.



> ### What goes into an init file?
>
> Defaults and aliases.
>
> A default specifies a set of _bindings_. If a parameter is omitted
> from a command, and there's a binding for that parameter, it will be
> automatically inserted into the command as if the user had typed it.
>
> An alias is a short equivalent for a parameter. When a command line is
> provided by a user, aliases will be expanded inline.  A user can
> specifically
> mark an alias for expansion by prefixing it with "@"; if an alias
> appears on the command-line surrounded by whitespace, it will be
> replaced even if it isn't marked with an "@".
>
> For example, an init file could contain the following:
>
>     init=Init(
>       defaults={
>         "jobspec": "west/markcc/test/myservice",
>         "config_file": "./src/aurora/myservice.aurora"
>       },
>       aliases={
>         "east": "east/markcc/test/myservice",
>         "c": "east",
>         "me": "markchucarroll"
>       })
>
>
> Then, if the user ran "`aurora job create`" without any parameters,
> it would automatically be expanded to
> "`aurora job create west/markcc/test/myservice
> ./src/aurora/myservice.aurora`".
>
> If a user ran "`aurora job create east`", the alias `east` would be
> expanded to "east/markcc/test/myservice", and the missing config file
> parameter would
> be instantiated using the default, to create a command-line:
> "`aurora job create east/markcc/test/myservice
> ./src/aurora/myservice.aurora`".
>
> If a user ran "aurora create @c/@me/test/myservice", the two aliases would
> be expanded, and the omitted configuration parameter would be added:
> "`aurora job create east/markchucarroll/test/myservice
> ./src/aurora/myservice.aurora`".
>

What if a user ran "aurora east"?



> ### Config Files
>
> The aurora client will look for a configuration file in the following
> locations, in order:
>
>    1. A file named "AuroraInit" in the current directory.
>    2. A file named "AuroraInit" in the sequence of parent directories of
> the
>      current directory up to the nearest repository root.
>    3. A file named ".aurora" in the user's home directory.
>

I think that the names of all these files should be named the same.  Unless
we wish to make the last location be inside the directory $HOME/.aurora.
 In other words, the file $HOME/.aurora/AuroraInit.  I personally like
having the directory, as it bundles other things in one location in the
future.

I'm not too enamored on the capitalization as well.  We have case
preserving filesystems, but case insensitive for lookup/etc.  I'd be
tempted to keep it all lower case, possibly separating the words using
dots, or dashes.  More likely dashes.


Like most other files loaded by the aurora client (job configuration files,
> hook files), the init file is a Pystachio configuration. It uses the
> following schema:
>
>     class Init(Struct):
>       defaults=Map(String, String)
>       aliases=Map(String, String)
>
> The configuration defined by an init file is the object of type `Init`
> that is assigned to the variable `init` in the init file.
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message