Merge pull request #1225 from tidymodels/checklists

Author: EmilHvitfeldt

.Rbuildignore

@@ -19,3 +19,4 @@ derby.log
 ^codecov\.yml$
 ^LICENSE\.md$
 ^man-roxygen$
+^vignettes/articles$

DESCRIPTION

@@ -75,7 +75,7 @@ ByteCompile: true
 Config/Needs/website: C50, dbarts, earth, glmnet, keras, kernlab, kknn,
     LiblineaR, mgcv, nnet, parsnip, quantreg, randomForest, ranger, rpart, 
     rstanarm, tidymodels/tidymodels, tidyverse/tidytemplate, rstudio/reticulate,
-    xgboost
+    xgboost, rmarkdown
 Config/rcmdcheck/ignore-inconsequential-notes: true
 Config/testthat/edition: 3
 Encoding: UTF-8

vignettes/articles/.gitignore

@@ -0,0 +1,4 @@
+*.html
+*.R
+
+/.quarto/

vignettes/articles/checklists.Rmd

@@ -0,0 +1,115 @@
+---
+title: "Dev checklists"
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+These are checklists used by the tidymodels team. If you want to use them to add models and/or engines in your own package, you will have to adapt them somewhat.
+
+Copy these checklists into the corresponding GitHub issue.
+
+
+## Checklist for adding a new model
+
+All these items should be added to *parsnip*, unless otherwise specified.
+
+```
+* [ ] Create the main modeling function (e.g. `nearest_neighbors()`). When choosing argument names, check for existing ones across other model types which could be reused, e.g., `trees` for the number of trees is used across different tree-based models like `rand_forest()` and `boost_tree()`.
+
+* [ ] Register the model and a mode in the parsnip model “database” with `parsnip::set_new_model()` and `parsnip::set_model_mode()`. [[example]](https://github.com/tidymodels/parsnip/blob/c54f07b7e1f7ce164aab8f95bc7b1356b68558c8/R/proportional_hazards_data.R)
+
+* [ ] Create an `update()` method.
+
+* [ ] Add parameter objects for main parameters to *dials*, if needed. See [How to create a tuning parameter function](https://www.tidymodels.org/learn/develop/parameters/) for more details.
+
+* [ ] Write unit tests for the basic modeling function (independent of the engines). 
+
+* [ ] Add a pkgdown entry.
+
+* [ ] Add model description to the internal `model_descs` tibble.
+
+* [ ] Run `purrr::map(parsnip:::extensions(), ~ library(.x, character.only = TRUE))`.
+
+* [ ] Run `parsnip:::update_model_info_file()`.
+
+* [ ] Make sure that no entries are removed from `inst/models.tsv`.
+
+* [ ] Add a documentation entry in `NEWS.md`.
+```
+
+
+## Checklist for adding a new engine
+
+Engines may live in parsnip or an extension package.
+
+```
+* [ ] Write the initial functions that will populate the parsnip model “database”. For example,	`parsnip::set_fit()` and so on. Suggested file name: `{model_name}-data.R`. [[example]](https://github.com/tidymodels/censored/blob/efbb1cf3b2ba8bca5de65acc3c8b665dec35631c/R/decision_tree-data.R#L13-L83)
+
+* [ ] _[extension pkg]_ Make sure that `parsnip::set_dependency()` has an entry for the package that contains the engine definition as well as the actual dependencies. [[example]](https://github.com/tidymodels/censored/blob/efbb1cf3b2ba8bca5de65acc3c8b665dec35631c/R/decision_tree-data.R#L14-L21)
+
+* [ ] _[extension pkg]_ Put the `set_*()` calls in a wrapper function that will register the model with parsnip. Suggested name: `make_{model name}_{engine name}()`. [[example]](https://github.com/tidymodels/censored/blob/efbb1cf3b2ba8bca5de65acc3c8b665dec35631c/R/decision_tree-data.R#L12) 
+
+* [ ] _[extension pkg]_ Add the registration functions to `.onLoad()` in the `zzz.R` file. [(example)](https://github.com/tidymodels/censored/blob/efbb1cf3b2ba8bca5de65acc3c8b665dec35631c/R/zzz.R#L13) 
+
+* [ ] Engine-specific tuning parameters: Necessary parameter objects [[example]](https://github.com/tidymodels/dials/blob/d47dc47f42ad9c190d7f4a1ec85db0e385345ec0/R/param_num_knots.R) should go into *dials* and the `tunable()` method [[example]](https://github.com/tidymodels/parsnip/blob/bdc28548fd46493b52b408b6c1e04e1f80d0abdf/R/tunable.R#L338-L345) should go into parsnip. This needs a tibble which links engine arguments to dials parameter objects [[example]](https://github.com/tidymodels/parsnip/blob/bdc28548fd46493b52b408b6c1e04e1f80d0abdf/R/tunable.R#L206-L215).
+
+* [ ] Optionally create methods for `translate()` and `check_args()` to handle engine-specific cases. These `.{model name}` methods should go into parsnip, even if the engine is defined in an extension package, as they may contain code for various engines distributed across multiple extension packages. [(example)](https://github.com/tidymodels/parsnip/blob/c54f07b7e1f7ce164aab8f95bc7b1356b68558c8/R/proportional_hazards.R#L85:L98')
+
+* [ ] Write unit tests for the engine-specific features. 
+
+* [ ] Write unit tests for model-specific features which require an engine. If parsnip does not contain _any_ engines for the model, put these in the extension package.
+
+* [ ] Write the engine-specific documentation. This documentation always goes into parsnip, regardless of where the engine is defined. See the [README](https://github.com/tidymodels/parsnip/blob/main/inst/README-DOCS.md) for the parsnip documentation system.
+
+* [ ] If the engine is added in parsnip, update `vignettes/articles/Examples.Rmd`. If the engine is added in an extension package: does it have a corresponding article that needs updating? Does the README list available models/engines and needs updating?
+
+* [ ] Add a documentation entry in `NEWS.md`.
+```
+
+
+## Checklist for documenting a new engine
+
+Engine documentation always goes into parsnip, regardless of where the engine lives.
+
+```
+* [ ] Make sure that you have the most recent release versions of devtools and roxygen2 installed. 
+
+* [ ] Add a new Rmd file to `parsnip/man/rmd` called `{model}_{engine}.Rmd`. [[example]](https://github.com/tidymodels/parsnip/blob/c54f07b7e1f7ce164aab8f95bc7b1356b68558c8/man/rmd/decision_tree_rpart.Rmd)
+
+* [ ] Write the actual documentation in `{model}_{engine}.Rmd`.
+
+* [ ] Make use of existing templates for topics like preprocessing requirements and case weights. Add templates if appropriate.
+
+* [ ] Add a new R file to `parsnip/R` called `{model}_{engine}.R`. [[example]](https://github.com/tidymodels/parsnip/blob/c54f07b7e1f7ce164aab8f95bc7b1356b68558c8/R/decision_tree_rpart.R)
+
+* [ ] Make sure to have `@includeRmd man/rmd/{model}_{engine}.md details`
+
+* [ ] Make sure to have `@name details_{model}_{engine}`.
+
+* [ ] Use `@keywords internal`.
+
+* [ ] Make sure that the packages in `parsnip:::extensions()` are installed.
+
+* [ ] Make sure that the `rmd_pkgs` listed in `parsnip/man/rmd/aaa.Rmd` are also installed. [[example]](https://github.com/tidymodels/parsnip/blob/main/man/rmd/aaa.Rmd#L20:L21)
+
+* [ ] Run `purrr::map(parsnip:::extensions(), ~ library(.x, character.only = TRUE))`.
+
+* [ ] Run `parsnip:::update_model_info_file()`.
+
+* [ ] Make sure that no entries are removed from `inst/models.tsv`.
+
+* [ ] Restart your R session (with `Shift + Cmd + 0` on MacOS).
+
+* [ ] Run `parsnip:::knit_engine_docs()`. There is an optional `pattern` argument to filter which documentation files are being processed. Note that this needs to execute `knit_engine_docs()` from an installed version of parsnip as opposed to parsnip being loaded via `devtools::load_all()`.
+
+* [ ] Check output for errors. 
+
+* [ ] Run `devtools::document()`.
+
+* [ ] Reinstall parsnip and check that the main modeling function has an entry for your engine. If it does not, was the model added to the parsnip model database? 
+```