Skip to content

Instantly share code, notes, and snippets.

@bitprophet
Last active December 14, 2015 13:58
Show Gist options
  • Save bitprophet/5097406 to your computer and use it in GitHub Desktop.
Save bitprophet/5097406 to your computer and use it in GitHub Desktop.

The setup:

  • Some top level tasks
  • A 'docs' submodule
  • docs.build is configured to be the default task for 'docs'
  • So, 'invoke docs' == 'invoke docs.build'. Either is allowed.

The question is, how should this setup display in --list? Our options:

  1. Fab 1.x style: display both, no indication of what maps to what:

    $ invoke --list
        top
        level
        docs
        docs.clean
        docs.build
        docs.browse
    
  2. Super-compact style: display only the default/shorthand. Kind of meh, "hides" the "real" task name:

    $ invoke --list
        top
        level
        docs
        docs.clean
        docs.browse
    
  3. Compact style: focus on the default/shorthand, but display the "real" name alongside:

    $ invoke --list
        top
        level
        docs (docs.build)
        docs.clean
        docs.browse
    
  4. Doubled-up/highly explicit style: still show what the default maps to, but ALSO show the "real" name in-place:

    $ invoke --list
        top
        level
        docs (docs.build)
        docs.clean
        docs.build
        docs.browse
    
  5. Variation on either of the above two, the "alongside" display could be compacted a bit, e.g.:

    $ invoke --list
        top
        level
        docs (.build)
        docs.clean
        docs.build
        docs.browse
    

    or:

    docs(.build)
    

    or:

    docs[.build]
    

    or so forth.

@aaugustin
Copy link

$ invoke --list
    top
    level
    docs.clean
    docs.build (default)
    docs.browse

or

$ invoke --list
    top
    level
    docs.clean
    docs[.build]
    docs.browse

@bitprophet
Copy link
Author

Had also considered docs (.build) which is similar to @aaugustin's docs[.build]. Originally I rejected this style because it felt not obvious enough, but it is an elegant way of displaying the information.

EDIT: I'm not really a huge fan of @aaugustin's 1st example because it doesn't make it quite clear enough that docs by itself is a legal task identifier.

EDIT 2: Added his 2nd form / my earlier version of same, to the main gist.

@dstufft
Copy link

dstufft commented Mar 6, 2013

I like 4 or 5 or @aaugustin's. 1-4 I don't really like.

@johnthedebs
Copy link

I'm a fan of docs[.build]. Doesn't hide anything, makes the list compact, and it clearly says 'typing this is optional' in unix style.

@dcramer
Copy link

dcramer commented Mar 6, 2013

Either #3 or #4. A normal person would have no idea what's going on. This thread has enough context that anyone can answer because they understand what it is from the beginning, but that's not how it would be in normal use.

@dcramer
Copy link

dcramer commented Mar 6, 2013

Also dont listen to @dstufft he's drunk :)

@dstufft
Copy link

dstufft commented Mar 6, 2013

Drink Drank Drunk

@myusuf3
Copy link

myusuf3 commented Mar 6, 2013

I would vote for #4 all the valid commands are clear to the user, albiet the default in the brackets would be confusing without saying it actually defaults to that, like @aaugustin's first example but binding it to the command.

Maybe:

$ invoke --list
    top
    level
    docs [default: docs.build]
    docs.build
    docs.clean
    docs.browse

or

$ invoke --list
    top
    level
    docs (default: docs.build)
    docs.build
    docs.clean
    docs.browse

@bitprophet
Copy link
Author

@myusuf3 My main issue with having the word 'default' here, is that the default-ness isn't really what's important, all that really matters to a user in this context is A) which identifiers are available/allowed, and B) the fact that 'docs' is the same as calling 'docs.build'.


It was late when I posted this, and I just remembered now that this needs to account for non-default aliasing as well. For example, let's pretend we have a top level task release which is an alias of deploy (i.e. deploy was decorated with @task(aliases=['release'])). We might want something like:

$ invoke --list
    deploy (release)
    level
    docs (docs.build)
    docs.build
    ...

Seems like this gets cluttered fast if we allow defaults/aliases' "real" targets to have their own lines, so I think from that angle, it's best to be compact and only show any given identifier once. (See e.g. svn help output for prior art here.)

That solves aliases. Given a default task is an "alias" of sorts to its collection/namespace, I think I'll go with consistency for now:

$ invoke --list
    deploy (release)
    docs (docs.build)
    docs.clean
    docs.browse

First release will be an 0.9 series so I reserve the right to backtrack on any of these opinions after folks actually start using it :D

@bitprophet
Copy link
Author

Second thought, if we're focusing on the target of an alias w/ its aliases in parentheses, that actually implies it's more consistent to put default tasks' collection names in parens too. I.e. backwards from the above:

$ invoke --list
    deploy (release)
    docs.build (docs)
    docs.clean
    docs.browse

Will go with this for now. Again, subject to change & likely to have different list format options available either way (e.g. ye olde nested view).

@myusuf3
Copy link

myusuf3 commented Mar 6, 2013

👍 on the last one actually quite clear.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment