[Opinions Requested] CommandBox generators, quick and easy vs wizards

Communities CommandBox CLI
1

Luis and I would like some feedback on how to proceed with some of our “generator” style commands such as “init” or “coldbox create app”. There are different use cases we’re imagining.

Use Case #1
Some people know what they want, and just want to get there with the least amount of characters typed and time taken. These people might also be automating and don’t want any interactivity.

init name=foo
coldbox create app myApp

Done! This approach is quick and easy for someone just wanting to throw a site together, ignore optional items, or reduce typing.

Use Case #2
Other people want a friendly, interactive approach. Perhaps they aren’t familiar with all the possible options and they’d prefer an experience like so:

init
Enter name (The human-readable name for this package) : myPackage
Enter version (The version for this package, please use semantic versioning - 0.0.0) : 1.0.0
Enter private (Would you like to mark your package as private, which prevents it to submit it to ForgeBox)(Yes/No) : yes
Enter shortDescription (A short description for the package) : This is my cool package
Enter author (The author of the package, you!) : Brad Wood
Enter keywords (A nice list of keywords that describe your package) : Brad, Cool, Package
Enter homepage (Your package’s homepage URL) : http://bradwood.com
Enter ignoreList (add commonly ignored files to the package’s ignore list)(Yes/No) : box.json, tests/, readme.txt

coldbox create app
Enter name (The name of the app you want to create) : myApp
Enter skeleton (The name of the app skeleton to generate) : AvancedScript
Enter directory (The directory to create the app in and creates the directory if it does not exist. Defaults to your current working directory.) :
Enter init (“init” the directory as a package if it isn’t already) (Yes/No) : no
Enter installColdBox (Install the latest stable version of ColdBox from ForgeBox) (Yes/No) : no
Enter installColdBoxBE (Install the bleeding edge version of ColdBox from ForgeBox) (Yes/No) : yes
Enter installTestBox (Install the latest stable version of TestBox from ForgeBox) (Yes/No) : yes

Each of those lines above would be a prompt that would pause execution while waiting for the user to input values. This would help you through the process if you weren’t aware of the options or just enjoyed the question/answer style. This is common with other tools like Yeoman generators.

Your opinion:

This is where you come in.

  • Which of those two behaviors should be default with CommandBox?
  • Which would you use more often?
  • How can we support both easily?
  • Two separate commands?
  • A --wizard flag?

Thanks!

~Brad

ColdBox Platform Evangelist
Ortus Solutions, Corp

E-mail: brad@coldbox.org
ColdBox Platform: http://www.coldbox.org
Blog: http://www.codersrevolution.com

2

Brad,

Honestly I wouldn’t use this command but every so often. Maybe even once a year as 99% of what I work on is maintenance items.

So… my suggestions would be:

Q. Which of those two behaviors should be default with CommandBox?
A. The wizard should be default

Q. Which would you use more often?
A. wizard

Q. How can we support both easily?
A. not sure what you’re getting at here

Q. Two separate commands?
A. No

Q. A --wizard flag?
A. I would do a --silent flag instead

Chris Tierney
CF Webtools

3

Hey Brad,

I think this is awesome that you want to support both ways.

I think by default the short version of the commands would be best and just pass in the named arguments you need(which is what I do now). For most I think it’s easy enough to type “coldbox create help” and see which arguments are needed.

I know I would use the short version way more frequently than the wizard.

I think a --wizard flag would be ideal instead of 2 different commands to do the same thing. It’s short, descriptive and should be pretty obvious as to what it is going to do.

Just my 2 cents. I’m sure there will be varying opinions.

Ben

4

  • Which of those two behaviors should be default with CommandBox?
    Default should be non-interactive

  • Which would you use more often?
    non-interactive

  • How can we support both easily?
    extend the functionality of the current init / create app to watch for the --wizard flag (personally I’d prefer it called interactive), if found just step through each argument, display hint, wait for response, when given a blank response use default

  • Two separate commands?
    not really

  • A --wizard flag?
    Sure, but again, I’d prefer --interactive

5

How have other language’s package managers solved the same challenge?

Distill the approaches from various other package managers, see what works, see what could be done better, etc.

Come up with an approach that takes the best from everything, buts comes together as a cohesive approach.

THEN ask the community whether there’s anything else to add.

6

Thanks for the feedback, Adam. Luis and I have already done the first three, and now we’re on step 4 :slight_smile:

We have an idea of where we’d like to go but we disagreed on what the most common use-case was so I decided to poll the community as well.

Thanks!

~Brad

ColdBox Platform Evangelist
Ortus Solutions, Corp

E-mail: brad@coldbox.org
ColdBox Platform: http://www.coldbox.org
Blog: http://www.codersrevolution.com

7

Cool.

Personally I’d prefer a file to put the settings in, rather than an interactive UI. The file can have as much annotation and example in it as you like, like say an httpd.conf or php.ini file. It can also either include default values, or specify what they will be if they have to be inferred from the environment.

This perhaps doesn’t quite answer your question, but I see a slight functionality gap between your option 1 and option 2, so neither of them seemed like the right fit (for me personally. I’m not second-guessing what other people might want).

8

Ah yes, I’m glad you brought that up since I think it fits here well. Luis and I have discussed what it would look like to be able to set default values for command parameters. That’s a feature I noticed while looking at other CLI task runners. From as simple as setting the --recurse flag to always be true in the “rm” command or defaulting the “author” param to “Brad Wood” for the “init” command.

We’ve discussed having system-level settings as well as project level settings, where the latter overrides the former. We’d probably go with a JSON file, but nothing has been decided for sure. I definitely think that can be part of a long-term solution though for a dev to set and forget certain param defaults that they don’t want to have to enter each time.

Thanks!

~Brad

ColdBox Platform Evangelist
Ortus Solutions, Corp

E-mail: brad@coldbox.org
ColdBox Platform: http://www.coldbox.org
Blog: http://www.codersrevolution.com

9

My vote:

Non-interactive by default. --interactive or -i or somesuch for going through wizard. That said, I like how when you have required arguments that aren’t supplied the framework prompts you. I’m presuming this is just for the optional arguments?

D

10

the framework prompts you.

Shh, don’t use the “framework” word! It scares ColdFusion developers :slight_smile:

I’m presuming this is just for the optional arguments?

Well, to date with CommandBox I’ve only set stuff to required if it was absolutely necessary. Anything that could be defaulted was to allow for the simplest possible commands. In “interactive” mode, everything would basically become required.

Thanks!

~Brad

ColdBox Platform Evangelist
Ortus Solutions, Corp

E-mail: brad@coldbox.org
ColdBox Platform: http://www.coldbox.org
Blog: http://www.codersrevolution.com

11

Well, to date with CommandBox I’ve only set stuff to required if it was absolutely necessary. Anything that could be defaulted was to
allow for the simplest possible commands. In “interactive” mode, everything would basically become required.

Exactly. And this is why I think it should not be the default behaviour. An optional interactive flag to force a prompt for all arguments regardless of the command developers intentions around making args optional or required.

However, thinking around giving the developer of the command more ultimate control, you could also do something like:

/**

  • @somearg.forcePrompt true

  • @somearg.hint Enter the meaning of life

  • @somearg.default 42
    */

function run( any someArg ){

}

This way the developer can force the prompt if the argument is not supplied already as well as provide a default value (the prompt should probably show the default with [42] or somesuch.

D

12

Oh, and you could also have the developer override the default interactive/non-interactive for a command through annotations… of course.

13

Interesting. To be honest, we were thinking the interactive bit would just be implemented by the commands that wanted to support it simply by declaring that parameter and then checking it . I hadn’t really thought about the flag being something special that CommandBox would look for and enforce outside of the command. I’ll have to think about that for a bit too as it might simplify things.

Thanks!

~Brad

ColdBox Platform Evangelist
Ortus Solutions, Corp

E-mail: brad@coldbox.org
ColdBox Platform: http://www.coldbox.org
Blog: http://www.codersrevolution.com