Function deprecation

Introduction

We encounter circumstances when a function requires significant modifications that might disrupt the flow of the original function (e.g., changing argument names, adding new arguments, etc.) or it simply need a thorough re-branding. Still, we don’t want to lose the existing function. It is feasible to notify existing users of those functions about the updates made so that people do not have to wonder why a function breaks or no longer works. The {lifecycle} package was explored while tackling a related issue and was incorporated into our package development workflow. This document describes how function deprecation was used for re-branding/renaming a function.

Please see the next section for a more in-depth look at the {lifecycle} package and its complete capabilities.

Further reads

Application

To offer a more consistent API with our crunch functions, the g6tr.survey::srv_gather_MR_crunch() function was deprecated and renamed to g6tr.survey::crunch_gather_mr() .

The code snippet below shows a sketch of original (pre-deprecation) implementation of the g6tr.survey::srv_gather_MR_crunch() function.

#' 
# documentation goes here...
#' @export
srv_gather_MR_crunch <- function(foo, bar) {
  ## Implementation of srv_gather_MR_crunch()
}

The idea behind this method function is to rename g6tr.survey::srv_gather_MR_crunch() without breaking existing code. We can move the implementation to g6tr.survey::crunch_gather_mr(), then call it from g6tr.survey::srv_gather_MR_crunch() along with a deprecation message.

#' 
#' @description 
#' `r lifecycle::badge("deprecated")`
#' 
#' `srv_gather_MR_crunch()` was renamed to `crunch_gather_mr()` to create a more
#' consistent API.
#' @keywords internal
#' @export
srv_gather_MR_crunch <- function(foo, bar) {
  lifecycle::deprecate_warn("0.3.4", "crunch_gather_mr()", "srv_gather_MR_crunch()")
  crunch_gather_mr(foo, bar)
}

# documentation goes here...
#' @export
crunch_gather_mr <- function(x, y) {
  ## Implementation of srv_gather_MR_crunch()
}

The code snippet above shows the implementation of the g6tr.survey::crunch_gather_mr() function. The original implementation was moved to the new function, and whenever the old (deprecated) function is called, a message appears telling the user to switch over to the new function.

Here’s what happens if you call g6tr.survey::srv_gather_MR_crunch()

Warning message:
`srv_gather_MR_crunch()` was deprecated in g6tr.survey 0.3.4.
Please use `crunch_gather_mr()` instead.
This warning is displayed once every 8 hours.
Call `lifecycle::last_lifecycle_warnings()` to see where this warning was generated.