Lifecycle Stages Reference

Lifecycle Stages Reference

Table of Contents

• Stage Diagram
• Stable
• Experimental
• Deprecated
• Superseded
• Retired Stages

Stage Diagram

experimental --> stable --> deprecated
                   |
                   +--> superseded

Lifecycle stages apply to packages, functions, arguments, or specific argument values.

Stable

The default stage. Functions are stable when the author is satisfied with the interface.

Promises:

• Breaking changes avoided where possible
• Breaking changes happen gradually through deprecation

Breaking changes reduce working code: removing functions/arguments, narrowing valid inputs, or changing output types.

Not breaking changes: Bug fixes that happen to break code relying on buggy behavior.

Experimental

For functions released without long-term stability promises. Author reserves the right to make breaking changes without deprecation cycle.

Guidelines:

• Packages with version < 1.0.0 are at least somewhat experimental
• Non-CRAN packages require active relationship with maintainers

Deprecated

Function has a better alternative and is scheduled for removal.

Deprecation stages (in order):

1. Soft deprecated (deprecate_soft()) - Warns only:

   • Users calling from global environment
   • Developers running tests
   • Does NOT warn when called indirectly by another package

2. Deprecated (deprecate_warn()) - Warns all users once per 8 hours

3. Defunct (deprecate_stop()) - Errors with helpful message about replacement

Superseded

Function has a known better alternative but won't be removed. Receives only critical bug fixes.

Key difference from deprecated:

• No warning emitted
• Documentation explains recommended alternative
• Function preserved indefinitely (safer than stable in some ways)

Examples: tidyr::gather() and tidyr::spread() superseded by pivot_longer() and pivot_wider().

Retired Stages

No longer recommended:

• Questioning - Author uncertain about function; not actionable for users
• Maturing - Between experimental and stable; unclear actionable information