OEP-21: Deprecation and Removal#
OEP |
|
Title |
Deprecation and Removal |
Last Modified |
2025-04-28 |
Authors |
Greg Sham <gsham@edx.org>,
Nimisha Asthagiri <nimisha@edx.org>,
Diana Huang <dkh@edx.org>,
Sarina Canelake <sarina@axim.org>
Feanil Patel <feanil@axim.org>
|
Arbiter |
Matt Tuchfarber <mtuchfarber@edx.org>
|
Status |
Accepted |
Type |
Process |
Created |
2018-05-18 |
Review Period |
2018-06-06 - 2018-06-20 |
Abstract#
This document defines a formal process for proposing, communicating, deprecating, and removing legacy and unneeded code in the Open edX platform.
Motivation#
Without a clear process for removing legacy code, developers hesitate to do so, leading to redundant implementations and dormant features that slow down development.
Benefits of code removal include:
Reducing maintenance burden and costs [OREILLY]
Improving project learnability and navigation [OREILLY]
Enabling better refactoring and optimization [OREILLY]
Reducing runtime footprint [INFOQ]
Encouraging continuous improvement [INFOQ]
High-Level Overview of Code Removal Process#
Process States#
The following sections describe each state in the deprecation and removal process.
Draft#
Initial state where code is identified for removal but no one has committed to coordinating the process.
A GitHub issue (or ticket) is created with the “Deprecation (DEPR) Ticket” template in the relevant repository (either in the repository to be deprecated, the repository where the to-be-deprecated component exists, or in public-engineering (see the DEPR board README for more details)):

This ticket remains in Draft until someone claims it as coordinator.
When to Consider Removal#
New implementation replaces old functionality
Static/runtime analysis shows code is never executed
Feature has very low adoption
What Can Be Removed#
User features (APIs, frontend, backend)
Modular components (Django apps, Frontend apps, XBlocks)
Outdated technologies or frameworks
Temporary feature toggles
Deprecated interfaces
RFC (Request for Comments)#
A coordinator has claimed the ticket and is actively gathering community feedback. During this phase:
Announce the proposed deprecation on:
Open edX Discourse Deprecation Announcements category (see template below)
Slack channels #general and any relevant working groups (e.g., #wg-frontend, #wg-build-test-release, #wg-maintenance)
Allow time for feedback (typically 2 weeks, but negotiable)
Respond to concerns and update the proposal as needed
If significant issues arise, be willing to extend the feedback period or revise the plan. For complex cases, consider consulting the Deprecation Working Group for guidance.
When posting to the Open edX Discourse Deprecation Announcements category, you can use the following template:
Subject: Deprecation/Removal: <Technology Name> <repo>#<issue-number>
- Body:
Hello.
We plan to deprecate and remove <Short description of the technology>.
Please read openedx/<repo>/issues/<issue-number> for more information and to post any questions or comments. The proposed deadline for comments before acceptance is <Target Accepted Date>.
Once the ticket is accepted, removal won’t happen until <Breaking Changes Unblocked Target Date>.
After acceptance, all future notifications around removal will only be posted to the GitHub issue, so be sure to watch that issue if you want further updates.
Thank you. <Your name>
Once the Discourse message is posted, add a link to the Discourse thread in the GitHub issue.
Plan Accepted#
After the RFC period and once all community concerns are addressed, the coordinator updates the ticket to “Plan Accepted” status. At this point:
The deprecation plan is officially approved
No new usage of the deprecated code should be introduced
Code should be marked as deprecated:
REST API: Add to docstring “Deprecated <link-to-gh-issue>”
JavaScript: console.log(“<Technology name> is deprecated. See <link-to-gh-issue>.”)
Python: warnings.warn(“<Technology name> is deprecated. See <link-to-gh-issue>.”, DeprecationWarning)
Feature toggles: Set expiration date as in OEP-17
GitHub repo: Follow OEP-14 for archiving
For larger changes, include a link to the deprecation ticket in the release notes for the next named release.
After acceptance, the ticket will proceed to either:
“Transition Unblocked” when a replacement is ready, or
Stay in “Plan Accepted” and wait for the negotiated timeline (default: 6 months) before proceeding to “Breaking Changes Unblocked”
Transition Unblocked#
This state indicates that a replacement for the deprecated code is ready and available. During this period:
Both old and new implementations operate in parallel
Users have time to transition to the new implementation (default: 1 month)
Feature flags/toggles control which implementation is active
The DEPR ticket should clearly communicate:
How to enable/disable each implementation
Any changes to default settings
Documentation for the new implementation
This transition period provides a safe migration path before breaking changes occur.
Breaking Changes Unblocked#
In this state, support for the old implementation has been officially dropped and developers can begin removing code. This state can be reached either:
Directly from “Plan Accepted” after a negotiated waiting period (default: 6 months), or
From “Transition Unblocked” after the transition period (default: 1 month)
During this phase:
Remove related code from frontends, APIs, and backends
Remove any feature flags introduced during transition
Update documentation to remove references to the old implementation
Keep the DEPR ticket updated with progress and any issues encountered
Users should expect the deprecated code to stop working at any point during this phase.
Plan Completed#
This is the final state, reached when all aspects of the deprecation and removal plan have been completed. When removal is complete:
Add the DEPR ticket to the wiki page for the next Open edX named release
Update the DEPR ticket’s state to “Plan Completed” with a final comment
Announce completion in the #wg-depr-slash-and-burn Slack channel
This state marks the successful conclusion of the deprecation and removal process.
Timeline#
The deprecation process follows these default timeframes, though all are negotiable based on complexity and impact:
Draft to RFC: When a coordinator claims the ticket
RFC Period: 2 weeks for community feedback
Plan Accepted to Breaking Changes Unblocked: 6 months (if no replacement needed)
Transition Unblocked Period: 1 month for users to migrate to the new implementation
Breaking Changes to Plan Completed: Varies based on removal complexity
When scheduling removal, consider the Open edX named release cycle (currently 6 months). The 6-month default waiting period ensures that operators have some warning before functionality is removed.
References#
Change History#
2025-05-23#
Clarify that “ticket” in this context refers to a GitHub ticket made using the DEPR template.
2025-04-28#
Restore and update the Discourse announcement template.
2025-04-15#
Updated process with new workflow states
Simplified document for greater clarity and conciseness
2024-04-12#
Changed process to require every DEPR have a coordinator.
2023-06-21#
Update Discourse template to describe how to stay up to date on removal status.
2022-11-01#
Simplified guidance around the earliest named release and removal dates.
Clarify that proposal can be made while incomplete, as long as they aren’t communicated until they are complete.
2022-07-05#
Add suggestion for monitoring.
2022-06-03#
Suggest alignment with release cycle
2022-02-08#
Migrate from Jira to GitHub Issues/Projects
2021-04-26#
“Removal dates” has become synonymous with “Accepted dates”, so we are eliminating them to clarify the process.
2021-02-05#
Added TL;DR section and workflow visuals
2019-01-02#
Recommend codebase impact review as part of DEPR process
2018-11-02#
Describes the process in specific ordered steps for one to follow.
Adds references to external docs.
Updates information on the JIRA ticketing process.
2018-06-21#
Document created