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.

@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