openedx / openedx/edx-toggles

Improve DEPR process for toggles

Open
#283 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
6
Forks
16
PR merge metrics
No merged PRs in 30d

Description

The following are a number of ideas for improving deprecation for toggles.

  1. These could be split out into separate tickets as needed.
  2. These were originally sourced from https://openedx.atlassian.net/wiki/spaces/AC/pages/2554331530/Toggles+and+Settings+Documentation.

Questions:

  • How can we ensure that newly added temporary toggles are handled by maintainers, and don't become random future DEPR work?
    • Can we have an SLA for maintainers for removing temporary toggles? Especially to apply to new ones.
    • What's the best way to move forward on this?

Proposals:

  • Add annotation for toggle_target_value (get name reviewed) to document whether to keep the True or False case once removed.
    • This would be required for temporary toggles.
    • Is it useful to have this in the code, or is some of this DEPR metadata better kept in the DEPR ticket alone?
    • We could just document that this detail should be added to the description for now.
  • Ensure (lint) a properly formatted date for toggle_target_removal_date annotation.
  • Here are examples with toggle_target_removal_date of None, even though it is required.
    • Note: This whole section is meant to be under the lint toggle_target_removal_date bullet, but indentation isn't working correctly.
      • Regarding linting, what if people want to use a named release instead? Should they just use its date?
      • Many of the examples also added unnecessary text to toggle_warnings that toggle_target_removal_date was not set.
      • Possibly authors documented during docathon, and were afraid to set a date.
      • How-to was since updated with proposal for how to choose a date.
      • Linting failure help text could point to these docs.

Additional Notes:

Moved to separate tickets:

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the linked Toggles and Settings Documentation and the additional notes in issue 284, then review the separated work in issues 284 and 324. Done means the toggle annotation, date-linting, maintainer-process, and documentation questions have been given concrete scope in those tickets rather than remaining as proposals here.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
developer-experience
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.