...
The first step is to realize an upgrade is even needed. We track the major Open edX dependencies which trigger recurring upgrade projects in this spreadsheet (which includes a link at the bottom to the code that generates it). The data is reviewed quarterly by 2U’s Arbi-BOM squad to identify upcoming upgrade needs, but anyone is welcome to create an issue or pull request to flag a missing dependency or stale data. The more complete this is, the better we can plan ahead. The official web sites of each software project are the authoritative source of information about support window end dates, although endoflife.date is also a very useful resource.
...
Create the issue in the platform-roadmap repository, and give it the “maintenance” label.
Add the checklist at the bottom of this page to the issue’s description.
Add the new issue to the Backlog column of the https://github.com/orgs/openedx/projects/4/views/1 project. Set any of the project’s custom fields whose values are known; common choices may include:
“Proposed by” - your organization’s name
“Platform map - Super Level” - Architecture/Platform
“Strategy” - Platform
“Type” - Maintenance
...
Find the date when support of the version currently in use ends.
Find the last date prior to that when the branches will be cut for a new Open edX release, according to the Open edX release scheduleRelease Schedule .
If there are compelling releases to upgrade earlier, pick the branch cut date for an earlier release as appropriate. (For example, major React versions get security patches indefinitely, but more and more related packages start requiring newer versions to work correctly.)
Set the roadmap issue’s milestone to be the corresponding release name.
If other upgrade projects are slated for the same Open edX release, stagger the completion dates if at all possible. We don’t want to be struggling to complete 3 major upgrades concurrently with wrapping up work on the release. Add an explicit completion date to the roadmap issue, and explain why it was chosen.
...
If new information is discovered that could help with other parts of the upgrade (solutions for tricky parts of the upgrade, new codemods for handling some of the code updates, unanticipated problem points to watch out for, etc.), the project documentation should be updated and the changes should be announced to other participants in the upgrade project.
...
Update the support windows spreadsheet to correctly indicate the version now used.
Announce the successful completion of the upgrade!
Make sure any deployment instructions make it into the release notes of the next Open edX named release. Communicate with the Build-Test-Release Working Group to make sure this gets done satisfactorily.
Remove any CI matrix entries for no-longer-supported versions of the dependency. For packages, this typically can’t be done until all of the services using them have completed the upgrade. Services are more free to do this relatively soon after the upgrade is successfully deployed.
Remove the https://github.com/orgs/edx/projects/17/views/1 board view created for the upgrade.
Stop running repo health checks which are no longer relevant. We may just want to skip the checks rather than deleting them, to make it easier to reuse them for the next similar upgrade.
Mark the roadmap issue for the upgrade as complete.
Do a retrospective meeting + asynchronous conversation to collect feedback on what went well, what could have been better, and what we can do even better next time. Update this document and the pages it links to if appropriate, and write and assign issues for any necessary followup work.
Move the root Confluence page for this upgrade’s docs under Past Upgrades.
If any external dependencies were discovered to be unsatisfactorily maintained, schedule work to replace them or (if necessary) take over maintenance of them ourselves. See Handling Outdated Dependencies for more details on this.
Appendix: Roadmap Issue Checklist
Add the following block of Markdown to the description of the upgrade’s main roadmap issue, and check items off as they are completed.
| Code Block |
|---|
Please use the following checklist to perform the upgrade according to the [Upgrade Project Runbook](https://openedx.atlassian.net/wiki/spaces/AC/pages/3660316693/Upgrade+Project+Runbook), distilled from lessons learned during previous major upgrade projects. See the full runbook for more details on each step.
```[tasklist]
### Tasks
- [ ] [Create a roadmap issue](https://github.com/openedx/platform-roadmap/issues/new/choose) in the platform-roadmap repository
- [ ] Add this checklist to the roadmap issue's description
- [ ] Add the "maintenance" label to the roadmap issue
- [ ] Add the roadmap issue to the Backlog column of the [Open edX Roadmap](https://github.com/orgs/openedx/projects/4/views/1) project
- [ ] Set appropriate values for the roadmap project's custom fields for the issue (especially "Proposed by", "Platform map - Super Level", "Strategy", and "Type")
- [ ] Set an appropriate release milestone for the roadmap issue
- [ ] Add an explicit target completion date to the roadmap issue description, and explain there why it was chosen
- [ ] Select an orchestration team
- [ ] Name the orchestration team in the roadmap issue description
- [ ] Create a repo health check to identify most/all of the repositories impacted by the upgrade (and ideally, whether or not the upgrade is believed to be complete)
- [ ] Create a new value for the "Project" field in the [Maintenance](https://github.com/orgs/edx/projects/17/views/1) project board for this upgrade project
- [ ] Create a new view in the Maintenance project board that filters down to only the issues in this upgrade project
- [ ] Create an issue in each impacted repository for the upgrade, and add it to the Todo column of the [Maintenance](https://github.com/orgs/edx/projects/17/views/1) project board; specify at least the "Project" and "Source" field for each issue (and "Owner" also if you're a 2U or Arbisoft employee)
- [ ] Create a [task list](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-tasklists) in the roadmap issue listing all of the impacted repository issues
- [ ] Create a page under [Upgrades](https://openedx.atlassian.net/wiki/spaces/AC/pages/1165395730) in Confluence for documentation related to the upgrade
- [ ] Add a link to the Confluence page from the roadmap issue
- [ ] Add a link to the roadmap issue from the Confluence page
- [ ] Document in a Confluence child page the changes believed to be most problematic and/or interesting about the upgrade
- [ ] Create a ticket to determine the appropriate amount of automation (codemods, repo health checks, etc.) to create for the upgrade
- [ ] Perform the automation discovery work and write upgrade instructions for all project participants in a Confluence child page
- [ ] Link to the upgrade instructions from the roadmap issue
- [ ] Send an [announcement](https://openedx.atlassian.net/wiki/spaces/AC/pages/3702325257/Upgrade-Related+Announcements) of the upgrade, asking code maintainers to read the upgrade instructions and select an upgrade service level for each impacted repository in its corresponding issue
- [ ] Create issues in [public-engineering](https://github.com/openedx/public-engineering) for each external dependency which still needs code changes and/or a release to support the upgrade
- [ ] Add the "help wanted" and "maintenance" labels to each public-engineering issue created above
- [ ] Add each public-engineering issue created above to the Maintenance project board
- [ ] Set appropriate values for the Maintenance project board custom fields for each added public-engineering issue
- [ ] Ask the Open edX developer community (especially Core Committers) for assistance with the added public-engineering issues
- [ ] Create [Build-Test-Release Working Group](https://github.com/orgs/openedx/projects/28) and/or 2U SRE tickets if they will need to do work for the upgrade
- [ ] Complete and update all of the created implementation tickets
- [ ] Deploy all of the updated services
- [ ] Update the [support windows spreadsheet](https://docs.google.com/spreadsheets/d/11DheEtMDGrbA9hsUvZ2SEd4Cc8CaC4mAfoV8SVaLBGI/edit#gid=195838733) to correctly indicate the version now used
- [ ] [Announce](https://openedx.atlassian.net/wiki/spaces/AC/pages/3702325257) the successful completion of the upgrade
- [ ] Make sure any deployment instructions make it into the release notes of the next Open edX named release (collaborate with the BTR WG)
- [ ] Remove any CI matrix entries for no-longer-supported versions of the dependency
- [ ] Remove the Maintenance project board view/tab created for the upgrade
- [ ] Stop running repo health checks related to the upgrade which are no longer relevant
- [ ] Schedule and run a retrospective meeting about the upgrade
- [ ] Update the [Upgrade Project Runbook](https://openedx.atlassian.net/wiki/spaces/AC/pages/3660316693/Upgrade+Project+Runbook) based on retrospective findings, if appropriate
- [ ] Mark the roadmap issue for the upgrade as complete
- [ ] Move the root Confluence page for this upgrade’s docs under [Past Upgrades](https://openedx.atlassian.net/wiki/spaces/AC/pages/1883865104)
- [ ] Ticket work to replace or take over dependencies which were found during the upgrade to be inadequately maintained
```
|