Feedback Requested: Upgrade Project Runbook

In an attempt to streamline and standardize the process of keeping Open edX on well-supported versions of its dependencies, I’ve written up an Upgrade Project Runbook. This distills the lessons learned from several previous upgrades of Django, Node, Python, Ubuntu, MySQL, MongoDB, Elasticsearch, etc., as well as some newer ideas for improving on recurring pain points in such projects. The process, if adopted, will have some degree of impact on all teams maintaining Open edX software as well as providing individual developers opportunities to help improve the health of the platform.

One of the newer ideas in the runbook is a central GitHub Project for tracking software maintenance and upgrade projects that span multiple Open edX software repositories, with its own draft documentation which I would also like feedback on. A prototype of the board has been created in the edx GitHub organization at Maintenance · GitHub for experimentation, but it will likely be moved to the openedx organization before we commit to broader usage of it.

Any and all feedback and suggestions are welcome. I’d love to learn about better ways of doing this that I’ve overlooked!


This is very thoughtful, thank you @jmbowman for putting it together. I added a bunch of comments and will mostly continue conversation there.

One thing that I want to be sure about is that the community and 2U have a commitment to work together. Looking at your board, it is very focused on 2U teams; if we put together our own tickets, we’ll need your help adding the right “owning team” tags. It’s also not clear to me, given the focus on 2U teams, if I’m supposed to participate, where I could help, if there are any tickets I can pick up. With some clarification on your intentions there, I think we can make the board a bit more approachable.

I don’t know GitHub boards well but we should figure out how to get the “Done” items off the board.

In a comment on the doc I flagged the problem in directing issues to the correct teams as something we need a public solution for; workflows to automate notifications of board activity might be a temporary solution for this particular case, with something like owner/maintainer tracking in Backstage a more general-purpose reference.

We definitely want to make it easy for people to help with upgrades, but have also historically encountered workflow problems getting PRs from teams other than the one owning the code merged in a timely manner. (This is true even for PRs from other teams within 2U like Arbi-BOM and FED-BOM, not just contributions from outside 2U.) So I mentioned helping upstream maintainers of our dependencies get their upgrades done as a great first step to helping in a way that doesn’t run afoul of that; that worked pretty well for the Django 3.2 upgrade. More and more Open edX code is being maintained outside of 2U, and the the teams doing that maintenance certainly have a role to play in getting their code updated. I’m working on addressing the root causes of the 2U problems with timely cross-team/org PR merges, and still thinking of other ways people can efficiently help out; further suggestions welcome!

Individual “Done” items can be archived, and there’s also an option to archive all “Done” items with a single action. We just haven’t decided on an archiving schedule yet, as there are only 13 issues in that state so far and the whole board workflow is still in review.

1 Like

Thanks for the reply, Jeremy. I agree automated workflows may be helpful, and leveraging Backstage as well. I appreciate your careful thought of this issue!