New recommendations for devstacks

Hey team,

I’m updating our onboarding course, because the guide to setting up your first devstack was severely out of date. Here is the Pull Request on GitLab. The main change is moving from the deprecated devstack to the Tutor devstack. But I’m also strongly recommending the use of mise, direnv[1], asdf, or some similar tool to manage the TUTOR_ROOT variable[2] and the python virtual environment.

I have a few questions:

  1. Can I get a reviewer(s) for the PR, ideally who can test the commands I included? (No rush)

  2. Does anyone else have any tips/recommendations around managing multiple tutor devstacks? Are my suggested mise settings reasonable?

  3. It seems like this course easily gets outdated, is rarely referenced by current team members, and is a pain to update. Should we move this guide to the handbook?

Here’s a quick screenshot of the new content:

You can also see it “live” here.

Ticket for this post: MNG-2787



  1. For what it’s worth, if anyone uses direnv instead of mise, here’s the equivalent .envrc that should go in each devstack root folder:

    export TUTOR_ROOT=$(pwd)
    export VIRTUAL_ENV=.venv
    layout python3
    
    ↩︎
  2. This essentially is a simpler way to manage multiple versions of Tutor, without needing a heavy solution like tvm. Felipe, who created tvm, recommends this simpler approach too. ↩︎

2 Likes

@braden, thanks for taking the time to update this.

  1. I will be happy to take the reviewer role here. (If someone else wants to do it for whatever reason, please feel free to switch me out).
  2. I have a couple of tweaks. I will mention it in the MR.
  3. I am not sure about this. Updating the content in the course is a pain compared to the handbook. However, devstack instructions change only every few years.

Thanks for the update @braden !

For the course, one other aspect to consider is that it’s one of the only area where we collaboratively dogfood the Open edX project as a team, and use it as learners and as instructors. This is important imho, even just once in a while. If it’s a pain for us to update the course, maybe we should make it easier to do that?

It’s only a pain to review it using a PR. Editing it in Studio is relatively easy. Though changing the slug ID of units is a big pain. Maybe we should add a feature for doing that within the Studio UI.

True, except that we don’t really use it as learners much. I assume that most people never look at the course again once they’ve been onboarded, unless they’re also working on updating it.

Yup, we have a similar problem while editing the Open Source Masterclass - one of the contributors made a script to edit those in bulk, but it is also a bit of a pain - and you have to do it before the file is merged, otherwise it breaks the history and the URLs. Imho the best would be to have the slug IDs being generated using the units/sections/etc titles, rather than being fully random - a bit like for blogs/CMS URL slugs. This could be a nice contribution, and also useful even when people don’t use PRs for reviews. :+1: This could be a good ticket for a core contributor in the team looking for additional hours.

Which would be the norm for courses I think, people would rarely take a course twice. And it’s part of why we have the course content in a course, rather than in the handbook: it’s only useful during the initial onboarding, while the handbook is meant as an ongoing reference. It’s still good to get to use Open edX immediately during onboarding imho, and then move on to the editing/instructor part afterwards.

Does anyone else have any tips/recommendations around managing multiple tutor devstacks?

I added this function to my ~/.zshrc from a tip I found in the DEPR proposal for TVM (tutor version manager):

# direnv tutor

function setdirenv() {
    echo "export TUTOR_ROOT=$(pwd)\nexport TUTOR_PLUGINS_ROOT=$(pwd)/plugins\nexport VIRTUAL_ENV=$(pwd)/venv\nexport PATH=$(pwd)/venv/bin:\$PATH" > .envrc
    direnv allow
}

The onboarding course is now updated with the latest devstack setup instructions! In particular, it recommends using mise and setting your TUTOR_ROOT env variable to the devstack’s directory.

Click “Next” from that page if you are interested in a tip on how using git worktree will let you save many GB of disk space by combining the datastore for your various edx-platform checkouts.

3 Likes