Skip to content

Commit

Permalink
docs: Update oep-0021-proc-deprecation.rst
Browse files Browse the repository at this point in the history
Add some more thoughts and we'll come back with more edits in the next meeting.
  • Loading branch information
feanil authored Jan 9, 2025
1 parent 9e8b580 commit 755bfcf
Showing 1 changed file with 21 additions and 15 deletions.
36 changes: 21 additions & 15 deletions oeps/processes/oep-0021-proc-deprecation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -218,14 +218,17 @@ considers the timing of the next `Open edX named release`_.

The removal date should default to 6 months of advance communication,
including at least 1 month window of overlapping support between old
and new features.
and new features. If you have a high level of confidence that it's not
used elsewhere and you still comunicate it to the community you may use
a more accelerated process which is as short as 2 weeks.

Additionally, the ability to negotiate dates on the DEPR ticket is an
explicit part of the process. This could include adjusting the default
dates for a specific ticket, or negotiating extensions as-needed (e.g.
difficulties that arise, or too many maintenance requests landing at
the same time, etc.). It could also include providing a very short
window for changes that don't require much warning.
window for changes that don't require much warning or where there are
very few actual users of the code.

The 6 month window has the benefit of givig at least one named release
(e.g. Redwood) worth of warning, because the named releases are
Expand Down Expand Up @@ -433,13 +436,8 @@ in the release notes of the next named release.
then the contributor must provide an ADR justifying its usage. This is because
using the deprecated feature obviously adds new technical debt to the system.

Deprecated
==========

If you decided to mark the code for deprecation during your Analyze_ or
`Monitor Feedback`_ phases, invest time in doing so and update the state of the
**DEPR** ticket to *Deprecated* once that is completed and make a comment on the
issue saying you've done so.
As a part of acceptance, all relevant warnings should go into code/documentation to indicate what
will be removed or replaced.

Here are some common ways to mark a technology as deprecated:

Expand All @@ -463,21 +461,29 @@ Here are some common ways to mark a technology as deprecated:
.. _OEP-17: https://open-edx-proposals.readthedocs.io/en/latest/oep-0017-bp-feature-toggles.html
.. _OEP-14 Archiving Open edX GitHub Repositories: https://open-edx-proposals.readthedocs.io/en/latest/oep-0014-proc-archive-repos.html

If the new version of the code will be using toggles/waffles, the names and settings of those waffles should be communicated to operators.
e.g. "If you don't want to use the new content libraries, set "xxx" waffle flag to false before that lands. Do we need more here?

Ready for Migration
===================
For code where there is a replacement, this state indicates that the replacement is ready for use and we are in a period where both the old and new code are working. This is a temporary state that allows developers/operators to migrate to the replacement option before the old code is removed. Unless otherwise negotiated/communicated, this stage will last one month to give everyone ample time to transition.

This state implies that there are flags or toggles to be able to switch between the two versions, and the DEPR ticket should communicate if the default is changing with enough time for operators to be able to set relevant flags to choose between the implementations.

Removing
========

When a team begins development work to remove the code, change the **DEPR**
ticket's state to *Removing* and make a comment on the issue saying you've done so.
This state indicates that support for the old implementation has been officially dropped and developers are able to begin removing code. If an item is in this state you should not expect the old implementation to work.

During this phase, remember the following:
During this phase, the following will occur:

* Implement the proposed and agreed upon migration path.
* Remove related code from all places, including the frontend, APIs, and
the backend, perhaps even in that order.
* Remove any related documentation on docs.edx.org_ and elsewhere.
* Remove any unnecessary feature flags introduced as a part of the transition.
* Remove any related documentation on docs.openedx.org_ and elsewhere.
* Continue to update the ticket with any delays or issues that may arise.

.. _docs.edx.org: https://docs.edx.org/
.. _docs.openedx.org: https://docs.openedx.org/

Removed
=======
Expand Down

0 comments on commit 755bfcf

Please sign in to comment.