Deprecate gSSURGO.Query() #3697

CHANGELOG.md

@@ -18,6 +18,10 @@ For more information about this file see also [Keep a Changelog](http://keepacha
 - `assign.treatments` has been renamed to `assign_treatments` and moved from `PEcAn.utils` to `PEcAn.MA` since that's the only place where it's used.
 - With new `PEcAn.MA::meta_analysis_standalone` function, `PEcAn.MA::run.meta.analysis.pft` now saves all files all at once _after_ the complete meta-analysis runs (and only if it is successful, including prior and posterior checks), rather than saving intermediate objects (like "JAGS-ified" data) as they are created.
 
+### Deprecated
+- `PEcAn.data.land::gSSURGO.Query()` is deprecated in favor of `extract_soil_gssurgo()` which uses the modern `soilDB` package. `gSSURGO.Query()` will be removed in a future release. (#3697)
+
+
 
 
 ## [1.10.0] - 2026-01-06

book_source/02_demos_tutorials_workflows/05_developer_workflows/03_coding_practices/01-coding-style.Rmd

@@ -43,3 +43,64 @@ When running `devtools::check()` a common warning relating to `dplyr` code is "n
 In [data-masking](https://dplyr.tidyverse.org/articles/programming.html#data-masking) situations (e.g. `mutate()`, `filter()`), you can eliminate this warning by using the `.data` pronoun.  For example, instead of `df %>% mutate(newvar = oldvar + 2)`, use `df %>% mutate(newvar = .data$oldvar + 2)`.
 
 In [tidy-select](https://dplyr.tidyverse.org/articles/programming.html#data-masking) situations (e.g. `select()`, `rename()`), you can eliminate this warning by using strings instead of naked column names. For example, instead of `df %>% select(y)` use `df %>% select("y")`.  Using `.data` inside of `select()` is [deprecated as of tidyselect v1.2.0](https://tidyselect.r-lib.org/news/index.html#lifecycle-changes-1-2-0)
+
+
+# Function Lifecycle Management
+
+## How to Deprecate a Function {#deprecate-function}
+
+When a function needs to be replaced or removed, follow these steps to properly deprecate it:
+
+1. **Add the `@deprecated` roxygen tag** with a message directing users to the replacement:
+   ```r
+   #' `old_function_name()` is deprecated, please use `package::new_function_name()` instead. 
+   ```
+
+2. **Add `.Deprecated()` call** at the top of the function body:
+   ```r
+   old_function <- function(...) {
+     .Deprecated("package_name::new_function_name")
+     # rest of function code
+   }
+   ```
+
+3. **Remove tests** that specifically test the deprecated function (but keep tests for the replacement function).
+
+4. **Update documentation**:
+   - Add a note to the package `NEWS.md` under a `## Deprecated` section
+   - Add a note to the main `CHANGELOG.md` under a `### Deprecated` section
+   - Mention the replacement function and that removal is planned for a future release
+
+5. **Keep the function in the codebase** for at least one release cycle to give users time to update their code.
+
+**Example PR**: See the deprecation of `gSSURGO.Query()` in favor of `extract_soil_gssurgo()` for a complete example of this process.
+
+## Removing Deprecated Functions {#remove-deprecated}
+
+After a function has been deprecated for at least one full release cycle:
+
+1. **Remove the function** from the R source file (usually in `R/` directory)
+
+2. **Update NAMESPACE**: Run `devtools::document()` to regenerate the NAMESPACE file without the removed function
+
+3. **Remove any remaining tests** that reference the function
+
+4. **Remove the `.Rd` documentation file**:
+   ```bash
+   git rm man/old_function_name.Rd
+   ```
+
+5. **Update documentation**:
+   - Add a note to `NEWS.md` under a `## Removed` section
+   - Add a note to `CHANGELOG.md` under a `### Removed` section
+
+6. **Search for any remaining references** to the function in:
+   - Vignettes
+   - Examples in other function documentation
+   - README files
+   - Book chapters
+
+   Update or remove these references as appropriate.
+
+**Important**: Never remove a function without first deprecating it for at least one release, unless it was never included in a released version or was never exported (not in NAMESPACE).
+

modules/data.land/NEWS.md

@@ -1,5 +1,7 @@
 # PEcAn.data.land 1.9.0.9000
 
+* `gSSURGO.Query()` is deprecated in favor of `extract_soil_gssurgo()` which uses the modern `soilDB` package. `gSSURGO.Query()` will be removed in a future release. (#3697)
+
 ## Fixed
 
 * `soil2netcdf()` no longer drops depth information for soils with only one layer. (#3785)

modules/data.land/R/gSSURGO_Query.R

@@ -1,6 +1,7 @@
 ############ Retrives soil data from gssurgo
 #' This function queries the gSSURGO database for a series of map unit keys
 #'
+#' `gSSURGO.Query()` is deprecated, please use `PEcAn.data.land::extract_soil_gssurgo()` instead (see issue #3697).
 #' @param mukeys map unit key from gssurgo
 #' @param fields a character vector of the fields to be extracted. See details and the default argument to find out how to define fields.
 #'
@@ -57,6 +58,8 @@ gSSURGO.Query <- function(mukeys,
                           fields = c("chorizon.sandtotal_r",
                                      "chorizon.silttotal_r",
                                      "chorizon.claytotal_r")) {
+  .Deprecated("PEcAn.data.land::extract_soil_gssurgo")
+
 
   ######### Retrieve soil