Improve DEPR process for toggles

[robrap]

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:

• See additional notes in Implement ADR on toggle-life-expectancy #284 for where to implement annotations improvements.

Moved to separate tickets:

• Implement ADR on toggle-life-expectancy #284
• Add toggle_removal_ticket annotation #324

[robrap]

Also relates to #315 where these annotations may all get used to find temporary toggles for removal.

[robrap]

+1 for toggle_depr_ticket annotation from today's meeting to review. People have used the existing annotation for a variety of tickets, including tickets for context, which may be useful but is different from quickly knowing if a DEPR ticket exists or does not exist.

[dianakhuang]

• Add annotation for toggle_depr_ticket to make it simpler to know if a toggle has an associated DEPR ticket.
  • Should this field be required for temporary toggles?
  • Is it better to create the DEPR ticket when creating the toggle?
  • Is it ok to use private tickets for short-lived toggles, or do we always want DEPRs for every newly created temp toggle?
  • Could there be an abbreviated process for new temporary toggles where they don't need to be announced?

Q: are temporary toggles added by anyone other than 2U?
A: yes, but usually these are added at the behest of 2U for rollout/safety purposes

Proposal: add the field and make DEPR tickets, but as we move forward, reconsider whether or not we want to make it required.

Recommend calling this field toggle_removal_ticket instead.

UPDATE: The new ticket for this work is #324

[bradenmacdonald]

Why do we even need DEPR tickets if the toggle had a removal date from the very first moment it was announced? Isn't the deprecation notice sort of built in in the first place?

[robrap]

Why do we even need DEPR tickets if the toggle had a removal date from the very first moment it was announced? Isn't the deprecation notice sort of built in in the first place?

@bradenmacdonald: Here are some general thoughts about what our process (whatever it is) should support:

• We'd like temporary toggles to actually get removed in a timely manner.
• It would be great if the people responsible for adding a toggle were responsible for removing it, although there could be exceptions to this desire.
• The removal date should be negotiable in the same way that DEPR removal dates are.
• It would be great if people who care about a toggle are informed about its status changes.

A DEPR ticket represents work that needs to go through a process to get to completion. It also has the inform part of the process built in. I could see the removal date in code being replaced by a toggle_date_added annotation (which is redundant to git blame information, but much quicker to review and get into reports). The main point of this date is to see how old a temporary toggle is, which might indicate its relative readiness for removal. A DEPR ticket would have more details, including the removal date, which again could be redundantly added to code.

These are my thoughts on the topic. Of course, we could skip the ticketing and just use the toggle report like you did. But, again, we are left with the questions: did the implementer choose a reasonable date for everyone, and who can we count on for removing the toggle?

Note: There other ongoing discussions about when a DEPR ticket is needed, and whether we would have other processes for certain things, or if we could have more specific streamlined DEPR processes for things like temporary toggles, etc. There is no right answer. Anything that helps us ensure that people clean-up where possible would be welcomed by me.