Confusing instructions during upgrade

Tutor
1

I wanted to upgrade my Tutor to Maple, so I ran:

% tutor local upgrade --from=lilac

It very quickly (too quickly?) said:

Your platform was successfuly upgraded from lilac to maple. Depending on your setup, you might have to rebuild some of your Docker images. You can do this now by running the following command in a different shell:

    tutor images build openedx # add your custom images here

Press enter when you are ready to continue [Y/n]

“you might have to rebuild some of your Docker images”: I don’t know what “might” means here, or whether I have to do this. I don’t know if I have custom images, I don’t think so. I’m not sure whether the instruction to run a command in another window means I have to do it before hitting Enter or not.

So I did it in another window before hitting Enter.

In the other window I ran:

% tutor images build openedx
⚠️  The current environment stored at /Users/nedbatchelder/Library/Application Support/tutor/env is not up-to-date: it is at v12.1.5 while the 'tutor' binary is at v13.0.3. You should upgrade the environment by running:

    tutor config save

This is a confusing message. I had just installed 13.0.3, but I guess the first window isn’t finished yet, so the env hasn’t been updated? Will I need to run this command? At this point I have two terminal windows, both of which have given me confusing and alarming messages, and told me to run other commands.

Once the second window finished (~25 minutes), I hit Enter on the first window, which had nothing else to do?

Is it possible to clarify some of these messages, and/or simplify this flow?

I love that Tutor gives me a simple way to run Open edX; I’m hoping we can make it even smoother.

1 Like
2

When the commands were all done, my local site was still Lilac (confirmed by search for “release line” in the home page HTML). So I tried tutor local reboot, which pulled more images, and ran the 25 minute rebuild again.

It’s not running yet, I have:

  File "/openedx/edx-platform/cms/envs/tutor/production.py", line 103, in <module>
    from django.utils.deprecation import RemovedInDjango40Warning, RemovedInDjango41Warning
ImportError: cannot import name 'RemovedInDjango40Warning' from 'django.utils.deprecation' (/openedx/venv/lib/python3.8/site-packages/django/utils/deprecation.py)

which is the subject of Install Maple: ImportError: cannot import name RemovedInDjango40Warning - #6 by sbernesto

3

The problem was persisting, perhaps because I had a Docker container still running from the Lilac era. Perhaps I needed a tutor local stop before the upgrade?

4

I agree that the Tutor documentation did not represent the actual steps necessary for upgrade (I would have also thought that I could just do the “tutor local upgrade --from=lilac” based on the documentation, had I not done an upgrade before and found it more complicated)

I posted my steps over here: Course Page Not Found In Maple Release - #11 by oedx

5

Hey Ned, good to see you here :slight_smile:

You are describing a real issue that has been partially discussed here in different places:

In my understanding, there are two problems:

  1. tutor local upgrade does not run tutor config save prior to printing that message about building Docker images. This specific problem is addressed in this pending PR: fix: upgrade from Lilac on k8s by regisb · Pull Request #554 · overhangio/tutor · GitHub
  2. The upgrade message that is printed in the standard output is poorly phrased. I can attempt to improve that message in the same PR.

Also, and maybe this wasn’t clear either: the way to upgrade a local installation is to run tutor local quickstart. The upgrade command will be run as part of quickstart. The only cases when you should run tutor local upgrade is when:

  1. The upgrade process failed for some reason and you want to restart it.
  2. You accidentally overwrote your environment with tutor config save and tutor has no way to know that it should upgrade.

Maybe this wasn’t clear from the docs or the tutor upgrade command help?

6

I definitely missed this in the instructions. 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”?

7

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.

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.

8

I’m not saying we should definitely change the name of the command. I’m just laying out my confusion. I just noticed something that may have added to it: Quickstart (1-click install) — Tutor documentation is the “quickstart installation method,” which reinforced my idea that the “quickstart” command was a once-and-done kind of thing.

9

I updated my PR to take into account most of the items that I listed above: fix: upgrade from Lilac on k8s by regisb · Pull Request #554 · overhangio/tutor · GitHub I will merge it now, event though there is no review, and I will publish a new release, to make sure that users who attempt to upgrade don’t make the same mistakes. I’ll keep an eye on emails and if there are bug reports I’ll make sure to push a fix quickly.

10

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.