From b65df9da424b5bb6dace72be76b98c832f8abcf1 Mon Sep 17 00:00:00 2001 From: Marcel Ramos Date: Tue, 23 Jan 2024 07:54:47 -0500 Subject: [PATCH] add examples to package deprecation (#116) Co-authored-by: lshep --- deprecation.Rmd | 27 +++++++++++++++++---------- package-end-of-life.Rmd | 16 +++++++++------- 2 files changed, 26 insertions(+), 17 deletions(-) diff --git a/deprecation.Rmd b/deprecation.Rmd index 4a826eb..b523363 100644 --- a/deprecation.Rmd +++ b/deprecation.Rmd @@ -6,27 +6,34 @@ that this process is minimally disruptive to your users. ## What to Deprecate? -Any function, class, method, or data that is no longer used or needed. +Any function, class, method, data, or even package that is no longer used or +needed. ## 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 development cycle ---------------|> + >|--- o feature introduced --- o feature removed ---|> + +Note that if you decide against using a function that you had introduced +**within the same development cycle**, you may simply remove the function +without following the standard function deprecation guidelines. It is expected +that the devel branch be unstable and be subject to API changes without notice +(though you may decide to communicate these changes to your users via the Bioconductor [support site][]). -However, if a function has existed in at least one released version + >| Bioconductor RELEASE_X_Y | Bioconductor development cycle |> + >|-- o feature introduced --|----- o feature removed --------|> + +However, if a function was published in at least one release version of Bioconductor, these guidelines _must_ be followed. The process of removing -a function, class, method, or any exported package object takes approximately -three release cycles (about 18 months). +a feature such as a function, class, method, or exported package object +takes approximately three release cycles (about 18 months). ## How To Deprecate A Function {#deprecate-function} ### Step 1: Deprecate the function -When you first decide to eliminate a function, you should mark it as +When you first decide to deprecate 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: diff --git a/package-end-of-life.Rmd b/package-end-of-life.Rmd index 20ebb93..56e93e8 100644 --- a/package-end-of-life.Rmd +++ b/package-end-of-life.Rmd @@ -1,7 +1,7 @@ # Package End of Life Policy The Bioconductor project strives to provide a software repository that is -stable and relevant to users across the community. Each year 100-150 new +stable and relevant to users across the community. Each year about 100-150 new software packages are added to the repository; as of Spring 2021 over 2000 packages are hosted. The Bioconductor Build System (BBS) installs, builds, and checks each software package every 24 hours. Regular execution of example, @@ -44,20 +44,22 @@ packages. Alternatively, a package maintainer may request package deprecation. The maintainer may have any number of reasons for deprecating their package. Some -common reasons: +common reasons include: 1. They no longer wish to maintain their package -2. The package has been superseded though other packages +2. The package functionality has been superseded by other packages -3. The package material has become out-dated and it makes sense to retire the +3. The package material has become out-of-date and it makes sense to retire the package. +4. Significant changes to the underlying technology e.g., a web API, have made +the package unmaintainable. + We ask that maintainers wishing to deprecate their package send an email notification to [bioc-devel][bioc-devel-mail] mailing list. The core team will ensure all necessary steps and notifications can occur. - ## End of Life process **Step I**: Deprecation @@ -149,5 +151,5 @@ interested replacement maintainer is asked to email the original maintainer and maintainer@bioconductor.org, to formally request permission to take over. Unless there is an explicit request for a package to be retired, Bioconductor will grant access to the interested replacement maintainer in accordance with open -source software licenses that Bioconductor packages require and [package naming -policy](#naming) that maintainers agree to upon submission. +source software licenses that Bioconductor packages require and +[package naming policy](#naming) that maintainers agree to upon submission.