Confusing instructions during upgrade

[regis]

@nedbat

I definitely missed this in the instructions.

We have a problem of clarity, both in the docs and the CLI help:

1. The docs say that you should run quickstart, but what most people will see is the big command tutor local upgrade --from=lilac verbatim paragraph.
2. The local upgrade command should be very explicit about the fact that users need to run quickstart.
3. Maybe the name of the local upgrade command should be improved.
4. When upgrading tutor from one major release to the next, there should be a more explicit warning to inform users of what they are doing (see this other conversation)
5. We should tell people that they almost certainly need to enable the tutor and the mfe plugins, if they are not enabled during upgrade.
6. A link to all of the breaking changes from the changelog should be prominently displayed during upgrade.
7. The docs should emphasize that upgrading from one major release to the next is potentially a risky endeavor and that downgrading is not possible. The docs should also link to the changelog.

@nedbat

One of the things that surprises me is how often I’m supposed to use quickstart. 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”?

I hear your argument, but let’s keep this conversation for later. 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. Maybe “quickstart” is not the best choice of word, and I’m open to suggestions, but we are not going to change it before the next major release.