Rename quickstart to launch

[kdmccormick]

Context

tutor <mode> quickstart is a very useful "one-click start" command that performs a variety of sub-tasks:

1. Checks RAM allocation.
2. tutor <mode> upgrade: performs a release upgrade if applicable.
3. tutor config save --interactive: runs an interview to get some basic config values and saves them.
4. tutor <mode> stop: stop any existing platform.
5. tutor <mode> dc pull: pull new images.
6. tutor <mode> start: brings up service containers.
7. tutor <mode> init: runs initialization scripts (migrate, make service users, etc).

I assume that quickstart in this context refers to "getting started quickly". However, the presence of the start command muddies this: quickstart sounds like it'd be an simplified version of the start command, where in reality it runs start plus a lot of other stuff.

@regisb, what would your thoughts be on changing either quickstart or start? Ideas:

• instead of quickstart:
  • setup
  • quicksetup
  • initstart
  • provision
  • go
  • launch <- winner
• instead of start:
  • up
  • serve

I know this would be a fairly major CLI change, so I understand if you'd rather leave it as-is.

(Discussion continued below)

Acceptance

• In time for Olive (released 2022-12-09):
  • Rename quickstart command to launch.
  • Update Tutor documentation.
  • Search for quickstart across the overhangio GH organization. If quickstart is referenced in any other Tutor repos, update them.
  • Temporarily alias quickstart to launch for backwards-compatibility. Mark quickstart as deprecated and warn users that launch should be used instead. Prior art: runserver is deprecated in favor of start
  • Create a new issue to remove quickstart in a following release (Palm, perhaps?)
  • Announce the change in the forums and Slack.

[regisb]

Ned raised a similar point in the forum: https://discuss.overhang.io/t/confusing-instructions-during-upgrade/2281/6
It's quite possible that the "quickstart" name is not very adequate -- I would attribute that to the fact that English is not my native language. But I failed so far to find a better alternative. Among your suggestiong, I like "setup" best.

• "quicksetup", "initstart": first time I see these terms.
• "go": too abstract.
• "provision": inaccurate (provisioning is "init" and it's only a part of "quickstart").

I think that we could keep "start". People immediately understand that "start" is the opposite of "stop". These verbs are simpler than "up/down". But you make a good point when you say that "quickstart" sounds like it's only a part of "start". I guess maybe we could go with "setup". I should sleep on this.

[kdmccormick]

From the forum post you linked @regisb , I found these excepts illuminating:

nedbat: To my ears, “quickstart” is something I would only run once per installation, at the very beginning. Is “start” in quickstart supposed to mean “start using Tutor” (what I thought), or “start the server”?

regis : The idea behind quickstart is that it’s the one and only command that most users should have to know about. There should be just one idempotent command, both for installing and upgrading.

What I read here is that quickstart is meant to be an all-purpose, beginner-friendly way of standing up Tutor. The answer to @nedbat's question above would be "both", in that:

• You run it once when you first start out.
• You can also run it over and over again in the future in order to start your instance while safely ensuring that it is provisioned and upgraded.

(On the other hand, start, much like upgrade is a subset of the quickstart command, and is aimed at more advanced users.)

I agree that setup is the only reasonable suggestion I put forward. Even so, I wonder if setup carries an implication of being something that you run once and should be run never again.

[kdmccormick]

Here's one more idea, which I admit is a little extreme, but I'll put out there for the sake of the discussion (EDIT: I realize in my next comment that this is a bad idea):

Merge both commands into one big start command, with the following semantics:

• If config.yml doesn't exist yet or if --setup was provided, then do what quickstart does today. That is:
  • Run the tutor config save --interactive interview.
  • If the platform is out-of-date: Ask if the user would like to upgrade.
  • Pull images.
  • Stop any existing platform.
  • Start the platform.
  • Run initialization scripts.
• Else if --initialize was provided:
  • Pull images.
  • Stop any existing platform.
  • Start the platform.
  • Run initialization scripts.
• Else if --pull was provided:
  • Pull images.
  • Stop any existing platform.
  • Start the platform.
• Else:
  • Just start the platform.

Under this system, first-time users would only need to run:

tutor <mode> start

After first-time setup, users would be able to use variations of start depending on what they needed to accomplish:

tutor <mode> start               # just start containers
tutor <mode> start --pull        # (re)start containers with fresh images
tutor <mode> start --initialize  # start+provision containers with fresh images
tutor <mode> start --setup       # re-run full idempotent setup (interview, upgrade, pull, provision, start)

[kdmccormick]

Okay, now that I've typed that ^ all out, I realize that it would be seriously confusing for a first-time user if they ran tutor local start, filled out an interview, but then exited before initialization scripts were run. Since a config.yml would have been generated, their subsequent run of tutor local start would not perform initialization, for reasons completely mysterious to a new user.

I am back to thinking that there need to remain two separate commands.

[kdmccormick]

After letting this sit for a month...

I still think quickstart obscures the fact that it's essentially an idempotent setup command, and is a superset of both init and start. I think setup is clearer in those regards.

At this same time, setup is a boring name in comparison. quickstart sounds more exciting, and highlights the fact that Tutor helps you quickly & easily get started with Open edX. This might seem like superficial reasoning, but this command is many folks' first ever exposure to Tutor & Open edX, so superficiality is worth something.

Given that, my new proposal is: tutor ... launch.

• it sounds like something you would do first, but also might do again in the future
• it sounds like a more involved version of start
• it hints to the fact that includes initialization steps (init)
• it's more exciting than setup

@regisb What do you think?

[regisb]

It's a little difficult for me to have a strong opinion on that nomenclature, as I'm limited by my own knowledge of English. All I can say is that I like "launch". The only problem I'd have is that "launch" is a little to similar to "start" in my own understanding -- but that's a very weak opinion, and it's probably unfounded.

I'd like to drag other people into this conversation, and in particular @nedbat who was the first to voice his concern about the "quickstart" command. Would it be clear to you what tutor local launch does? (i.e: an idempotent command that configures Open edX, starts a local platform and run initialization scripts)

[nedbat]

I like that "launch" won't be confusing the way "start" is. You can both start a project and start a server. And while you can launch a project, it's a ceremonial thing that wouldn't be used as the name of a command.

Are we overlooking the simpler "run"?

[kdmccormick]

Thanks @nedbat .

I like that "launch" won't be confusing the way "start" is. You can both start a project and start a server. And while you can launch a project, it's a ceremonial thing that wouldn't be used as the name of a command.

We wouldn't be renaming "start"; we'd be renaming "quickstart". Does that change your comment, or am I misunderstanding you?

Are we overlooking the simpler "run"?

"run" has its own meaning. For reference, the existing relevant tutor local ___ commands are:

  quickstart        Configure and run Open edX from scratch (nb: superset of both "init" and "start")
  init              Initialise all applications
  start             Run all or a selection of services.
  restart           Restart some components from a running platform.
  reboot            Reboot an existing platform
  stop              Stop a running platform
  exec              Run a command in a running container
  run               Run a command in a new container

[nedbat]

Oops, sorry, I had forgotten the context and misunderstood the proposal. Honestly, it's hard to find an existing word that easily conveys all of the things that quickstart does. I think "launch" is a novel enough word in this context that people will be less likely to jump to the wrong conclusion about it, so it's an improvement. It will still require continual education though, because of the unusual nature of the operations.

[regisb]

I think we are all in agreement here, so it's "go for launch" 🚀 We should make this change in Olive.

[kdmccormick]

Great! I added an acceptance criteria.

[Carlos-Muniz]

@kdmccormick I'd like to take this issue on!

[kdmccormick]

@Carlos-Muniz it's all you! Please just make the change on the nightly branch so that this change does not go out until Olive.

[kdmccormick]

Completed on Nightly.