About Deprecation
In the normal course of software development, a function, method, or other object may be removed. Here are some guidelines for ensuring that this process is minimally disruptive to your users.
What to Deprecate
Any function or method that is no longer used.
When to Follow These Guidelines
If you introduce a function into the devel branch of your package, then soon after decide not to use it, you may simply remove the function without following these guidelines. It is expected that the devel branch is unstable and subject to API changes without notice (though you may decide to communicate these changes to your users via the bioconductor mailing list).
However, if a function has existed in at least one released version of Bioconductor, these guidelines must be followed.
How To Deprecate
The full process for removing a function takes three release cycles (18 months).
Step 1: Deprecate the function
When you first decide to eliminate a function, you should mark it as
deprecated in the devel branch. Do this by calling .Deprecated()
inside the function. To do this, you must provide a replacement function
which should be used in place of the old function. Example:
myOldFunc <- function()
{
.Deprecated("myNewFunc")
## use new function, or remainder of myOldFunc
}
This causes a warning to be emitted whenever a user calls
myOldFunc()
. See ?.Deprecated
for more information.
Indicate in the man page of the old function that it has been deprecated, and
suggest a replacement function. Be sure the old function is not called in
man page examples or vignette code chunks; R CMD check
should
report this.
Ensure that if the user enters:
help("myOldFunc-deprecated")
that they are shown the manual page for the original old function, which should mention that the function is deprecated and point users towards the replacement function.
Additionally, a man page reachable by
help("myPackageName-deprecated")
should list the functions in your package that are deprecated and discuss the appropriate replacement functions. See
help("base-deprecated")
for an example.
Step 2: Mark the function as defunct
In the next release cycle, after your function has been deprecated, it must be made defunct in the devel branch. This means a call to the old function will return an informative error but not run any additional code. Example:
myOldFunc <- function()
{
.Defunct("myNewFunc")
}
See ?Defunct
for more information.
Additionally, ensure that a call to:
help("myPackageName-defunct")
shows a manual page that lists the defunct functions in your package, and discusses the appropriate replacements. See
help("base-defunct")
for an example. Make sure that
help("myPackageName-deprecated")
no longer lists your function.
Step 3: Remove the function
In the next release cycle, after your function has been marked as defunct, remove it entirely from your package R code and NAMESPACE in the devel branch. Also remove any man page content that documents the function.
Leave the man page from the previous step in place so that
help("myPackageName-defunct")
still shows the list of defunct functions and their appropriate replacements.