Deprecation 2.0

[bms63]

Strategy pre-1.0.0

From programming strategy guide - https://pharmaverse.github.io/admiraldev/articles/programming_strategy.html#deprecation

=====

As admiral is still evolving, functions or arguments may need to be removed or replaced with more efficient options from one release to another. In such cases, the relevant function or argument must be marked as deprecated. This deprecation is done in three phases over our release cycles.

Phase 1: In the release where the identified function or argument is to be deprecated there will be a warning issued when using the function or argument using deprecate_warn().

Phase 2: In the next release an error will be thrown using deprecate_stop().

Phase 3: Finally in the 3rd release thereafter the function will be removed from the package altogether.

Information about deprecation timelines must be added to the warning/error message.

Note that the deprecation cycle time for a function or argument based on our current release schedule is 3 months.

=====

• This was a move fast and break things type of process.

  • Pros: Got rid of code bloat, remove future maintenance needs
  • Pros: Removed duplicated functions and helped align argument names
  • Cons: Instability that users found frustrating
  • Cons: Deprecation Cycle was very tedious to maintain

Strategy at 1.0.0

This has not been codified into any guide only discussed on GitHub.

• Functions and arguments that we created pre-1.0.0 are being carried through with our deprecation cycle (see above)

• We are currently embracing superseded as a way to recommend functions to users that replace current functions

• In our new paradigm we are no longer deprecating any functions or arguments in admiral.

• Pro: Increases stability for new users

• Con: Increases code base to maintain for developers

  • Maintain old functions even if new function is superior
  • Now have a contract with users to apply bug fixes to old functions

• Con: More functions in reference documents increases search time for users...confusion.

Strategy post-1.0.0

Perhaps we should continue to deprecate functions through a process of superseding and then deprecating over a three year cycle.

Proposal:

• Functions that are superseded deprecated are given a two-year message cycle

  • Message recommends replacement function and timeline when this message will convert to a deprecation warning

• After two-year superseded deprecated function message is reached the message turns into a 1 year deprecation function warning

• After 1 year deprecation is reached the function is removed from the package

• Pro: Reduces number of functions we have to maintain

• Pro: Users are less overwhelmed with function options

• Con: Users will have to update their code over time

• Con: Developers have to maintain the cycle

[bms63]

@pharmaverse/admiral

Hi all, I put together some notes on our Deprecation/Superseded Strategy that we can discuss at the core meeting.

I'm worried that the only supersede strategy might introduce a lot of unnecessary code maintenance and documentation overload. I do think we should embrace some type of long-term deprecation strategy, i.e. 3 year or more till a function is removed.

Please put any thoughts here or we can discuss at the meeting. @pharmaverse/admiral_comm let us know your thoughts here if you have any advice concerns on deprecation!!

[bundfussr]

I think the post-1.0.0 strategy meets the needs of users much better. The ADaM scripts are recreated for each study. I.e., there is no user code which is used for a long period of time. Thus there is no need for superseding functions (in the sense that the superseded functions are kept forever).

I think we should not use the term "superseded". In the lifecycle package it is defined as:

A superseded function has a known better alternative, but the function itself is not going away . A superseded function will not emit a warning (since there’s no risk if you keep using it), but the documentation will tell you what we recommend instead .

For the first phase we could use something like "to be deprecated".

Before we remove the function I would add a period where the function is defunct, i.e., it is available but it issues an error.

[ddsjoberg]

I agree with @bundfussr . The way we're talking about superseded functions, the way we're discussing migrating users away from superseded functions...it all sounds like a long deprecation cycle (three years was thrown around at some point).

[manciniedoardo]

Decision: add to weekly agenda and make a decision either way.

@bms63 might have something to present. Then we can look to make an issue and codify our strategy.