From 00c3d49394c0e230d6324e9ecb20e972f84b7591 Mon Sep 17 00:00:00 2001 From: LiNk-NY Date: Thu, 2 May 2024 14:23:30 -0400 Subject: [PATCH] Update dataset deprecation guidelines --- deprecation.Rmd | 105 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 73 insertions(+), 32 deletions(-) diff --git a/deprecation.Rmd b/deprecation.Rmd index b523363..e419edd 100644 --- a/deprecation.Rmd +++ b/deprecation.Rmd @@ -110,51 +110,92 @@ Leave the man page from the previous step in place so that still shows the list of defunct functions and their appropriate replacements. -## How To Deprecate A Package Dataset {#deprecate-dataset} +## How To Deprecate An S3 Dataset {#deprecate-dataset} -### Step 1 - Save a promise object +### Step 1 - Create an S3 deprecation class -The initial step of deprecating a dataset is to signal to any users on -the devel branch of Bioconductor that the dataset will no longer be used. -This can be done using a `warning` message when the devel user loads -the dataset. In order to do this, we first create a promise object with -the same name as the dataset name using the `delayedAssign` function: +The initial step of deprecating a dataset is to signal to users that the +dataset will no longer be used. Alert the user with a `warning` message added to +its `print` method. To do this, first add the deprecation class to the dataset +object. Note that the class name here is arbitrary but it should be descriptive: - delayedAssign( - x = "pkgDataset", - value = { - warning("'pkgDataset' dataset is deprecated; see '?newData'") - pkgDataset - } - ) + class(pkgDataset) <- c("DeprecatedData", class(pkgDataset)) -You can also include the dataset as an output after the warning. -We then replace the original `.Rda` dataset file in the package with the -promise object and dataset using the `save` function: +Then serialize the class as an R object so that it can be loaded in the +package: - save("pkgDataset", eval.promises = FALSE, file = "data/pkgDataset.Rda") + save(pkgDataset, file = "data/pkgDataset.rda") -With the `eval.promises` argument set to `FALSE`, we can delay the evaluation -of the promise object until the user loads the data with -`data("pkgDataset", package = "yourPkg")`. The user will then get a warning -along with the dataset. The warning should include instructions that will point -the user to a new dataset or functionality that will replace the data, if -necessary. +or with `usethis`: -### Step 2 - Update documentation + usethis::use_data(pkgDataset, overwrite = TRUE) -After the promise object has been saved, we update the documentation to +### Step 2 - Create a print method + +Then create a print method for the new class that will print the warning +message: + + print.DeprecatedData <- function(x, ...) { + warning("'pkgDataset' dataset is deprecated; see '?newData'") + NextMethod() + } + +It is useful to guide the user to the replacement dataset or functionality +that will replace the data in the `warning` message. Note that this method +should be exported in the package's `NAMESPACE` file. + +### Step 3 - Update documentation + +After the dataset object has been saved, we update the documentation to reflect the changes and provide additional details and resources for users as necessary. It is recommended to include a "[Deprecated]" label in the data documentation title. -### Step 3 - Defunct the dataset +### Step 4 - Defunct the dataset + +In the following release cycle, upgrade the warning message to an error +message to indicate that it is no longer available. The data can then be +removed from the package. Remember to update the "[Deprecated]" +label in the documentation title to "[Defunct]". + +## How to Deprecate An S4 Dataset + +### Step 1 - Create an S4 deprecation class + +With S4, the process is similar to S3, but we need to create a new class +that inherits from the original class with `setClass`. The class name here +is arbitrary but should be descriptive: + + .DeprecatedData <- + setClass("DeprecatedData", contains = "S4Class") + +The `setClass` call creates a generator function which we can then use +to create an instance of the new class from the old object: + + myS4DataObject <- .DeprecatedData(myS4DataObject) + +We then serialize the object to disk so that it can be loaded in the +package: + + save(myS4DataObject, file = "data/myS4DataObject.rda") + +or by using `usethis`: + + usethis::use_data(myS4DataObject, overwrite = TRUE) + +### Step 2 - Create a show method + +Create a `show` method for the new class that will produce a warning message: + + setMethod("show", "DeprecatedData", function(object) { + warning("This dataset is deprecated; see '?newData'") + callNextMethod() + }) + +Note that this method should be exported in the package's `NAMESPACE` and +the `show` generic should be imported from the `methods` package. -In the following release cycle, you can update the warning message to indicate -that the dataset is defunct and remove it entirely from the promise object -i.e., from the expression in the `delayedAssign` function. We can also update -the "[Deprecated]" label in the documentation title to -"[Defunct]". +Note that steps 3 and 4 are the same as for S3 datasets. ## How to Deprecate a Package {#deprecate-package}