add examples to package deprecation (#116)

Co-authored-by: lshep <[email protected]>

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 <code>.Deprecated()</code>
 inside the function. To do this, you must provide a replacement function
 which should be used in place of the old function. Example:

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
 [email protected], 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.