Are there best/recommended practices to follow when renaming functions in a new version of a package?

Question

I\'m updating an old package and shortening a bunch of really long function names. How do I let a user know the the old function has been deprecated? I document everything with

Answer 1

Even though you are just shortening function names, I would still treat it with the same fanfare as any change to the public API of the package: with deprecation/defunct stages to the old functions as the new functions are brought in.

In the first phase, for each function you want to shorten the name of (let's call it transmute_my_carefully_crafted_data_structure_into_gold), you keep a function with that signature, but move all the actual code into your newly named function (let's call it alchemy).

Initially:

transmute_my_carefully_crafted_data_structure_into_gold <- function(lead, alpha=NULL, beta=3) {
  # TODO: figure out how to create gold
  # look like we are doing something
  Sys.sleep(10)
  return("gold")
}

First release with new names:

transmute_my_carefully_crafted_data_structure_into_gold <- function(lead, alpha=NULL, beta=3) {
  .Deprecated("alchemy") #include a package argument, too
  alchemy(lead=lead, alpha=alpha, beta=beta)
}

alchemy <- function(lead, alpha=NULL, beta=3) {
  # TODO: figure out how to create gold
  # look like we are doing something
  Sys.sleep(10)
  return("gold")
}

So that transmute_my_carefully_crafted_data_structure_into_gold starts as a thin wrapper around alchemy, with an additional .Deprecated call.

> transmute_my_carefully_crafted_data_structure_into_gold()
[1] "gold"
Warning message:
'transmute_my_carefully_crafted_data_structure_into_gold' is deprecated.
Use 'alchemy' instead.
See help("Deprecated") 
> alchemy()
[1] "gold"

If you make changes to alchemy, it is still carried by transmute_my_carefully_crafted_data_structure_into_gold since that just calls the former. However, you don't change the signature of transmute_my_carefully_crafted_data_structure_into_gold even if alchemy does; in that case you need to map, as well as possible, the old arguments into the new arguments.

In a later release, you can change .Deprecated to .Defunct.

> transmute_my_carefully_crafted_data_structure_into_gold()
Error: 'transmute_my_carefully_crafted_data_structure_into_gold' is defunct.
Use 'alchemy' instead.
See help("Defunct")

Note that this is an error and stops; it does not go ahead and call alchemy.

You could, in some later release, delete this function entirely, but I'd leave it in this state as a signpost.

You mentioned using using roxygen. When you make the first transition to deprecated, you can change the @rdname to package-deprecated, add a line at the beginning of the description saying it is deprecated, add the new function to the @seealso. When it changes to defunct, change the @rdname to package-defunct.