OEP-21: Deprecation and Removal¶

When to remove?¶

Here are a few common cases for code removal:

• There is now a new implementation that replaces the old implementation. If so, the old implementation should be deprecated and then removed in favor of the new.

• Static analysis or runtime analysis shows that the code is never executed on your Open edX instance. If so, it should be removed (if no one in the community requires it) or should become a pluggable extension since it’s not core to all instances.

• There is a legacy feature that never really saw the light of the day or was adopted by very few users. If so, this should be confirmed by usage analysis and then removed.

What to remove?¶

Here are a few technologies that are commonly removed:

• User features, including their APIs, frontend, and backend implementations

• Modular components, such as Django apps, Frontend apps, XBlocks

• Technologies, such as CoffeeScript, outdated frameworks

• Feature toggles used for temporary rollout and testing

• Interfaces, such as REST APIs and Plugin APIs

Analyze¶

When proposing a removal, consider the following analysis:

• Usage - Which users and services are currently using the code proposed for removal on your own Open edX instance? Perform a quick search across the edX codebase to gauge the level of impact and identify potential stakeholders. https://github.com/search?q=org%3Aopenedx+sample&type=Code

• Replacement - What, if any, is a viable replacement for the code being removed?

• Migration path - If there is existing high usage in the community, what is a viable automated migration path from the deprecated code to the removed code?

• Deprecation - Based on expected usage and effort to migrate, for how long should the deprecation period be?

Timeline¶

When determining target dates to propose for the removal process, consider that it will vary depending on team resources and the technology being removed. The importance of removal (as described in Motivation) should be communicated with all team members so the removal can be prioritized and completed in a timely manner. A suggested timeline is shown in the diagram below, which considers the timing of the next Open edX named release.

• Proposed on Day 1

• Communicated from Day 2 to Day 13

• Accepted on Day 14 (depending on influx of feedback)

• Deprecated/Removing/Removed - from Day 15 onwards (depending on resources and technology being removed). Consider when the next Named Release is cut; if it is very soon, you may wish to delay final removal until after the cut date.

Consider choosing deprecation and removal dates that allow for a full release cycle for transition planning. For example, a deprecation proposal could be accepted while Maple is being finalized, then implement the removal some time after Maple is released so that the removal itself will land in Nutmeg. (Removal could even happen as soon as a named release’s branches are cut, but this may interfere with fixes that need to be backported.) Any deployment following the named releases would then have a number of months to prepare before Nutmeg comes out.

This approach would be most appropriate for features that can be left in place for an extended period before removal and where a transition to an alternative would require a moderate to large amount of effort. For more trivial deprecations, it may be appropriate to simply deprecate and remove within the same release cycle.

Document¶

Do the following to document your proposal:

1. Create a GitHub Issue in the repo where the code being deprecated lives, and be sure to choose the “Deprecation (DEPR) Ticket” template. If your deprecation spans multiple repos, choose the primary/most relevant repo, or use the public-engineering project.

   Note

   While it is possible to create Issues with no template, it is strongly encouraged that you go to github.com/openedx/:repo/issues, click “New Issue”, and choose the DEPR template so you don’t miss any fields and automation works properly. The template fields help us more quickly address deprecation issues and reduce the amount of back and forth needed to make progress on work. If you must create an Issue outside the template, please preface your issue title with [DEPR].

2. When writing the ticket, include the following information:

   1. Title: The title of the ticket should read “[DEPR]: <technology name being deprecated>”.

   2. Proposal Date: the day the proposal is being put up for consideration.

   3. Target dates for: Accepted and Removed. See Timeline for considerations.

   4. Include in which Open edX named release the code will be removed. Reach out to the #wg-build-test-release in Slack if you’re not sure what to put here.

   5. Rationale: A few sentences explaining the rationale for removing this technology.

   6. Removal: A description with links to what is being removed.

   7. Replacement: A description with links to what it is being replaced by.

   8. If you plan to mark the code for deprecation, explain how in the Deprecation section. See Deprecated for considerations.

   9. If automated migration will be needed, explain your migration plan in the Migration section.

   10. If there is any additional publicly shareable information or data from your earlier analysis, include that in the Additional Info section.

3. Check that your ticket appears on the DEPR Project Board.

Now you are ready to communicate your proposal!

Announce¶

Announce your proposal to deprecate and remove to the following communication channels.

Monitor Feedback¶

Once announcements are made, update the GitHub Issue to the Communicated state.

Allocate time to be responsive to any and all feedback and input on your DEPR ticket. Update the ticket and the proposal, if neccessary, with any information that should be captured from the ongoing feedback. Continue to iterate and do this until the announced target Accepted date.

If during this time, there is a large amount of churn or concern, be open to adjusting the target dates and revisiting the proposal. If community alignment seems difficult, reach out to the Deprecation Working Group for directional guidance. In some cases, the proposal may need to be Abandoned entirely.