Lifecycle stages

A diagram showing the transitions between the fourmain stages: experimental can become stable and stable can becomedeprecated or superseded.

Stable

The default development stage is. A function is considered stable when the author ishappy with its interface, doesn’t see major issues, and is happy toshare it with the world. Because this stage is the default, functionswill only be given a stable badge if there’s some specific need to drawattention to their status.

Stability is defined in terms of breaking changes. Abreakingchange is a change that breaks code that uses the function asexpected. In general, breaking changes reduce the set of code that workswithout error, either by removing a function, removing a functionargument, or decreasing the set of valid inputs. Breaking changes alsoinclude changes to output type. If you imagine all the possible inputsto a function that return a result (and not an error), a breaking changemakes the set smaller.

Not all changes that cause your function to stop working are breakingchanges. For example, you might have accidentally relied on a bug. Whenthe bug is fixed, your code breaks, but this is not a breaking change. Agood way of making your code more robust to this sort of behaviourchange is to only use a function for its explicitly intended effects.For example, usingc() to concatenate two vectors will notput your code at risk because it clearly is the intended usage of thisfunction. On the other hand, usingc() just for the sideeffect of removing attributes is probably not a good idea. For example,if you had usedc(factor("foo")) to retrieve the underlyingintegers of a factor, your code will have broken when R added supportfor concatenating factors in R 4.1.0.

Stable functions come with two promises related to breakingchanges:

• Breaking changes will be avoided where possible. We’ll only makebreaking changes if we consider the long term benefit of the change tobe greater than short term pain of changing existing code.

• If a breaking change is needed, it will occur gradually, throughthe deprecation process described next. This gives you plenty of time toadjust your code before it starts generating errors.

Deprecated

A function has a betteralternative available and is scheduled for removal. When you call adeprecated function, you get a warning telling you what to use instead.For example, taketibble::as_data_frame():

df<-tibble::data_frame(x=1)#> Warning message:#> `data_frame()` is deprecated as of tibble 1.1.0.#> Please use `tibble()` instead.#> This warning is displayed once every 8 hours.#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was generated.

The deprecation warning tells you when the function was deprecated(in tibble 1.1.0, released in 2016), and what to use instead(tibble()). To avoid being too annoying, deprecationmessages will only appear once per session, and you can find out exactlywhere they come from by callinglifecycle::last_lifecycle_warnings().vignette("manage") provides more advice on handlingdeprecation warnings in your code.

Particularly important functions may go through two additional stagesof deprecation:

• Soft deprecated comes before deprecated. It’s agentler form of deprecation designed to prevent new uses of a functionand encourage package developers to move away from it. Soft deprecatedallows a package to change its interface to encourage package developersto update their code before their users are forced to change.

• Defunct comes after deprecated. In most cases, adeprecated function will eventually just be deleted. For very importantfunctions, we’ll instead make the function defunct, which means thatfunction continues to exist but the deprecation warning turns into anerror. This is more user-friendly than just removing the functionbecause users will get a clear error message explaining why their codeno longer works and how they can fix it.

Superseded

A softer alternative to deprecation is superseded. A¹ function has a knownbetter alternative, but the function itself is not going away . Asuperseded function will not emit a warning (since there’s no risk ifyou keep using it), but the documentation will tell you what werecommend instead .

Superseded functions will not receive new features, but will receiveany critical bug fixes needed to keep it working. In some ways asuperseded function is actually safer than a stable function becauseit’s guaranteed never to change (for better or for worse).

Experimental

Some functions are released in an stage. Experimental functions are made availableso people can try them out and provide feedback, but come with nopromises for long term stability. In particular, the author reserves theright to make breaking changes without a deprecation cycle. That said,there is some interaction between popularity and stability. Breaking apopular function, even if clearly labelled as experimental, is likely tocause widespread pain so we’ll generally try to avoid it.

In general, you can assume any package with version number less than1.0.0 is at least somewhat experimental, and it may have major changesin its future. The most experimental packages only exist on GitHub. Ifyou’re using a non-CRAN package you should plan for an activerelationship: when the package changes, you need to be prepared toupdate your code.

Superseded stages

We no longer use these stages, but we document them here because wehave used them in the past.