Merge pull request #66 from r-devel/CRAN-comments

Cran comments

_freeze/preface/execute-results/html.json

@@ -1,9 +1,11 @@
 {
-  "hash": "5a6e0e21e8e8168e1c9927b155b84912",
+  "hash": "293c910c7cd0ac1ff3a83c02c6abe6fa",
   "result": {
     "engine": "knitr",
-    "markdown": "---\ntitle: \"Preface\"\nsubtitle: \"\"\nformat: \n  html:\n    css: style.css\n---\n\n\n\n\n# Motivation\n\n<!-- add this --> \n\n# Introduction\n\nThe CRAN Cookbook has been developed as part of a special project grant from the R Consortium in 2024. The proposal is titled: **Improving the Skills of R Package Maintainers**. The goals of the project are:\n\n1. Educate a diverse cohort of young R developers to acquire the technical knowledge and skills required to participate in the continuous integration of R packages into the R ecosystem.\n2. Develop a new documentation solution with a Quarto website that is user-friendly for new R package maintainers on CRAN.\n3. Identify common CRAN submission issues and create a framework of \"problems\" and \"solutions\" that are easy to implement and discover.\n\n<!-- add more -->\n\n# Prerequisite\n\n- **Beginner to intermediate knowledge of R Programming**: This guide is designed to assist both first-time R package maintainers and those with experience who prefer to navigate a curated selection of the most common issues encountered when submitting to CRAN, as identified by CRAN Maintainers. It provides a 'best practices' approach to resolving R package issues to facilitate a successful re-submission to CRAN.\n\n\n- While not required, it's useful to have experience in debugging code. Submitting your R package to CRAN is a multi-step process that may involve communicating with multiple CRAN volunteers and updating your code, tests, examples, documentation, and other supplementary files to meet acceptance criteria. Developing strong debugging skills can be particularly valuable during this process, as it can help you effectively apply the examples in this cookbook to create custom solutions for updating your R package.\n\n\n# Acknowledgement\n\n- Thank you to the [R Consortium](https://www.r-consortium.org/) for funding and sponsoring this project!\n\n![](https://raw.githubusercontent.com/RConsortium/artwork/main/r_consortium/R_Consortium-logo-horizontal-color.svg){fig-align=\"left\"}\n\n## Contributors\n\n_Thanks to all contributors!_\n\nLluís Revilla ([@llrs](https://github.com/llrs))\n\n# Colophon\n\nThis cookbook is a Quarto website. To learn more about Quarto websites visit <https://quarto.org/docs/websites>. The cookbook is hosted on GitHub pages as part of the [Community R development resources](https://github.com/r-devel). The website is currently deployed with [local commands](https://github.com/r-devel/cran-cookbook/wiki/GitHub-Pages-Deployment).\n\n### Session info \n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nif (!requireNamespace(\"devtools\", quietly = TRUE)) {\n    install.packages(\"devtools\")\n}\nlibrary(devtools)\n```\n\n::: {.cell-output .cell-output-stderr}\n\n```\nLoading required package: usethis\n```\n\n\n:::\n\n```{.r .cell-code}\ndevtools::session_info()\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n─ Session info ───────────────────────────────────────────────────────────────\n setting  value\n version  R version 4.4.0 (2024-04-24)\n os       macOS Ventura 13.6.9\n system   x86_64, darwin20\n ui       X11\n language (EN)\n collate  en_US.UTF-8\n ctype    en_US.UTF-8\n tz       America/New_York\n date     2024-10-10\n pandoc   NA (via rmarkdown)\n\n─ Packages ───────────────────────────────────────────────────────────────────\n ! package     * version date (UTC) lib source\n P cachem        1.1.0   2024-05-16 [?] RSPM\n P cli           3.6.3   2024-06-21 [?] RSPM\n P devtools    * 2.4.5   2022-10-11 [?] RSPM\n P digest        0.6.36  2024-06-23 [?] RSPM\n P ellipsis      0.3.2   2021-04-29 [?] RSPM\n P evaluate      0.24.0  2024-06-10 [?] RSPM\n P fastmap       1.2.0   2024-05-15 [?] RSPM\n P fs            1.6.4   2024-04-25 [?] RSPM\n P glue          1.7.0   2024-01-09 [?] RSPM\n P htmltools     0.5.8.1 2024-04-04 [?] RSPM\n P htmlwidgets   1.6.4   2023-12-06 [?] RSPM\n P httpuv        1.6.15  2024-03-26 [?] RSPM\n P jsonlite      1.8.8   2023-12-04 [?] RSPM\n P knitr         1.48    2024-07-07 [?] RSPM\n P later         1.3.2   2023-12-06 [?] RSPM\n P lifecycle     1.0.4   2023-11-07 [?] RSPM\n P magrittr      2.0.3   2022-03-30 [?] RSPM\n P memoise       2.0.1   2021-11-26 [?] RSPM\n P mime          0.12    2021-09-28 [?] RSPM\n P miniUI        0.1.1.1 2018-05-18 [?] RSPM\n P pkgbuild      1.4.4   2024-03-17 [?] RSPM\n P pkgload       1.4.0   2024-06-28 [?] RSPM\n P profvis       0.3.8   2023-05-02 [?] RSPM\n P promises      1.3.0   2024-04-05 [?] RSPM\n P purrr         1.0.2   2023-08-10 [?] RSPM\n P R6            2.5.1   2021-08-19 [?] RSPM\n P Rcpp          1.0.13  2024-07-17 [?] RSPM\n P remotes       2.5.0   2024-03-17 [?] RSPM\n   renv          1.0.7   2024-04-11 [1] RSPM (R 4.4.0)\n P rlang         1.1.4   2024-06-04 [?] RSPM\n P rmarkdown     2.27    2024-05-17 [?] RSPM\n P sessioninfo   1.2.2   2021-12-06 [?] RSPM\n P shiny         1.9.1   2024-08-01 [?] RSPM\n P stringi       1.8.4   2024-05-06 [?] RSPM\n P stringr       1.5.1   2023-11-14 [?] RSPM\n P urlchecker    1.0.1   2021-11-30 [?] RSPM\n P usethis     * 3.0.0   2024-07-29 [?] RSPM\n P vctrs         0.6.5   2023-12-01 [?] RSPM\n P xfun          0.46    2024-07-18 [?] RSPM\n P xtable        1.8-4   2019-04-21 [?] RSPM\n P yaml          2.3.8   2023-12-11 [?] RSPM\n\n [1] /Users/jasminedaly/Desktop/R-directory/cran-cookbook/website/renv/library/macos/R-4.4/x86_64-apple-darwin20\n [2] /Users/jasminedaly/Library/Caches/org.R-project.R/R/renv/sandbox/macos/R-4.4/x86_64-apple-darwin20/2edc1867\n\n P ── Loaded and on-disk path mismatch.\n\n──────────────────────────────────────────────────────────────────────────────\n```\n\n\n:::\n:::\n",
-    "supporting": [],
+    "markdown": "---\ntitle: \"Preface\"\nsubtitle: \"\"\nformat: \n  html:\n    css: style.css\n---\n\n\n\n\n\n# Motivation\n\n<!-- add this --> \n\n# Introduction\n\nThe CRAN Cookbook has been developed as part of a special project grant from the R Consortium in 2024. The proposal is titled: **Improving the Skills of R Package Maintainers**. The goals of the project are:\n\n1. Educate a diverse cohort of young R developers to acquire the technical knowledge and skills required to participate in the continuous integration of R packages into the R ecosystem.\n2. Develop a new documentation solution with a Quarto website that is user-friendly for new R package maintainers on CRAN.\n3. Identify common CRAN submission issues and create a framework of \"problems\" and \"solutions\" that are easy to implement and discover.\n\n<!-- add more -->\n\n# Prerequisite\n\n- **Beginner to intermediate knowledge of R Programming**: This guide is designed to assist both first-time R package maintainers and those with experience who prefer to navigate a curated selection of the most common issues encountered when submitting to CRAN, as identified by CRAN Maintainers. It provides a 'best practices' approach to resolving R package issues to facilitate a successful re-submission to CRAN.\n\n\n- While not required, it's useful to have experience in debugging code. Submitting your R package to CRAN is a multi-step process that may involve communicating with multiple CRAN volunteers and updating your code, tests, examples, documentation, and other supplementary files to meet acceptance criteria. Developing strong debugging skills can be particularly valuable during this process, as it can help you effectively apply the examples in this cookbook to create custom solutions for updating your R package.\n\n\n# Acknowledgement\n\n- Thank you to the [R Consortium](https://www.r-consortium.org/) for funding and sponsoring this project!\n\n![](https://raw.githubusercontent.com/RConsortium/artwork/main/r_consortium/R_Consortium-logo-horizontal-color.svg){fig-align=\"left\"}\n\n## Contributors\n\n_Thanks to all contributors!_\n\n- Lluís Revilla ([@llrs](https://github.com/llrs))\n\n- Ivan Krylov ([@aitap](https://github.com/aitap))\n\n# Colophon\n\nThis cookbook is a Quarto website. To learn more about Quarto websites visit <https://quarto.org/docs/websites>. The cookbook is hosted on GitHub pages as part of the [Community R development resources](https://github.com/r-devel). The website is currently deployed with [local commands](https://github.com/r-devel/cran-cookbook/wiki/GitHub-Pages-Deployment).\n\n### Session info \n\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nif (!requireNamespace(\"devtools\", quietly = TRUE)) {\n    install.packages(\"devtools\")\n}\nlibrary(devtools)\n```\n\n::: {.cell-output .cell-output-stderr}\n\n```\nLoading required package: usethis\n```\n\n\n:::\n\n```{.r .cell-code}\ndevtools::session_info()\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n─ Session info ───────────────────────────────────────────────────────────────\n setting  value\n version  R version 4.4.1 (2024-06-14 ucrt)\n os       Windows 10 x64 (build 19045)\n system   x86_64, mingw32\n ui       RTerm\n language (EN)\n collate  German_Austria.utf8\n ctype    German_Austria.utf8\n tz       Europe/Vienna\n date     2024-11-08\n pandoc   3.2 @ C:/Program Files/RStudio/resources/app/bin/quarto/bin/tools/ (via rmarkdown)\n\n─ Packages ───────────────────────────────────────────────────────────────────\n ! package     * version date (UTC) lib source\n P cachem        1.1.0   2024-05-16 [?] RSPM (R 4.4.0)\n P cli           3.6.3   2024-06-21 [?] RSPM (R 4.4.0)\n P devtools    * 2.4.5   2022-10-11 [?] RSPM (R 4.4.0)\n P digest        0.6.37  2024-08-19 [?] RSPM (R 4.4.0)\n P ellipsis      0.3.2   2021-04-29 [?] RSPM (R 4.4.0)\n P evaluate      1.0.0   2024-09-17 [?] RSPM (R 4.4.0)\n P fastmap       1.2.0   2024-05-15 [?] RSPM (R 4.4.0)\n P fs            1.6.4   2024-04-25 [?] RSPM (R 4.4.0)\n P glue          1.8.0   2024-09-30 [?] RSPM (R 4.4.0)\n P htmltools     0.5.8.1 2024-04-04 [?] RSPM (R 4.4.0)\n P htmlwidgets   1.6.4   2023-12-06 [?] RSPM (R 4.4.0)\n P httpuv        1.6.15  2024-03-26 [?] RSPM (R 4.4.0)\n P jsonlite      1.8.9   2024-09-20 [?] RSPM (R 4.4.0)\n P knitr         1.48    2024-07-07 [?] RSPM (R 4.4.0)\n P later         1.3.2   2023-12-06 [?] RSPM (R 4.4.0)\n P lifecycle     1.0.4   2023-11-07 [?] RSPM (R 4.4.0)\n P magrittr      2.0.3   2022-03-30 [?] RSPM (R 4.4.0)\n P memoise       2.0.1   2021-11-26 [?] RSPM (R 4.4.0)\n P mime          0.12    2021-09-28 [?] RSPM (R 4.4.0)\n P miniUI        0.1.1.1 2018-05-18 [?] RSPM (R 4.4.0)\n P pkgbuild      1.4.4   2024-03-17 [?] RSPM (R 4.4.0)\n P pkgload       1.4.0   2024-06-28 [?] RSPM (R 4.4.0)\n P profvis       0.3.8   2023-05-02 [?] RSPM (R 4.4.0)\n P promises      1.3.0   2024-04-05 [?] RSPM (R 4.4.0)\n P purrr         1.0.2   2023-08-10 [?] RSPM (R 4.4.0)\n P R6            2.5.1   2021-08-19 [?] RSPM (R 4.4.0)\n P Rcpp          1.0.13  2024-07-17 [?] RSPM (R 4.4.0)\n P remotes       2.5.0   2024-03-17 [?] RSPM (R 4.4.0)\n   renv          1.0.7   2024-04-11 [1] RSPM (R 4.4.1)\n P rlang         1.1.4   2024-06-04 [?] RSPM (R 4.4.0)\n P rmarkdown     2.28    2024-08-17 [?] RSPM (R 4.4.0)\n P rstudioapi    0.16.0  2024-03-24 [?] RSPM (R 4.4.0)\n P sessioninfo   1.2.2   2021-12-06 [?] RSPM (R 4.4.0)\n P shiny         1.9.1   2024-08-01 [?] RSPM (R 4.4.0)\n P stringi       1.8.4   2024-05-06 [?] RSPM (R 4.4.0)\n P stringr       1.5.1   2023-11-14 [?] RSPM (R 4.4.0)\n P urlchecker    1.0.1   2021-11-30 [?] RSPM (R 4.4.0)\n P usethis     * 3.0.0   2024-07-29 [?] RSPM (R 4.4.0)\n P vctrs         0.6.5   2023-12-01 [?] RSPM (R 4.4.0)\n P xfun          0.48    2024-10-03 [?] RSPM (R 4.4.0)\n P xtable        1.8-4   2019-04-21 [?] RSPM (R 4.4.0)\n P yaml          2.3.10  2024-07-26 [?] RSPM (R 4.4.0)\n\n [1] C:/Users/benia/Desktop/cran-cookbook/cran-cookbook/renv/library/windows/R-4.4/x86_64-w64-mingw32\n [2] C:/Users/benia/AppData/Local/R/cache/R/renv/sandbox/windows/R-4.4/x86_64-w64-mingw32/e0da0d43\n\n P ── Loaded and on-disk path mismatch.\n\n──────────────────────────────────────────────────────────────────────────────\n```\n\n\n:::\n:::\n",
+    "supporting": [
+      "preface_files"
+    ],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],

code_issues.qmd

@@ -17,6 +17,12 @@ Change the abbreviation to the full words or use a different variable name.
 
 ### Details
 
+::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true}
+
+Please write TRUE and FALSE instead of T and F. Please don't use "T" or "F" as vector names.
+
+:::
+
 In R, `T` and `F` are variables being set to `TRUE` and `FALSE`, respectively. However, those variables can be redefined by the user since these are not reserved words as `TRUE` and `FALSE` are (see the [R Language Definition](https://cran.r-project.org/doc/manuals/r-release/R-lang.html#Reserved-words) for more details). This can result in unexpected code behavior as users of your package might have variables named `T`/`F`.
 
 ### Examples
@@ -55,6 +61,12 @@ Remove the code that sets the seed. If you want to set it specifically in your f
 
 ### Details
 
+::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true}
+
+Please do not set a seed to a specific number within a function.
+
+:::
+
 Changing the seed is not necessarily forbidden. However, users should be able to control which seed to use. Therefore, avoid code that changes the seed without user consent (e.g.: `set.seed(123)`). A good solution for allowing to set a seed is to add an argument `seed` to your function and set it conditionally. 
 
 ```{r, eval = FALSE}
@@ -91,6 +103,14 @@ You are using functions, like `print()` or `cat()`, to print unsuppressable outp
 Change `print()`/`cat()` to `message()`, `warning()`, `stop()`, or wrap them in `if(verbose){}`.
 
 ### Details
+
+::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true}
+
+You write information messages to the console that cannot be easily suppressed.
+It is more R like to generate objects that can be used to extract the information a user is interested in, and then print() that object. Instead of print()/cat() rather use message()/warning() or if(verbose)cat(..) (or maybe stop()) if you really have to write text to the console. (except for print, summary, interactive functions)
+
+:::
+
 Information messages, like loop counts or status updates, can clutter the console. While some users prefer this display, others appreciate less information on their console. The use of printing functions for console output is not forbidden on CRAN. However, this output must be suppressable by users. 
 
 :::{.callout-note}
@@ -151,6 +171,26 @@ Reset the changed options, in your functions by using [`on.exit()`](https://stat
 
 ### Details
 
+::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true}
+Please make sure that you do not change the user's options, par or working directory. If you really have to do so within functions, please ensure with an *immediate* call of on.exit() that the settings are reset when the function is exited.  
+e.g.:  
+...  
+oldpar <- par(no.readonly = TRUE) # code line i  
+on.exit(par(oldpar)) # code line i + 1  
+...  
+par(mfrow=c(2,2)) # somewhere after  
+...  
+e.g.:  
+If you're not familiar with the function, please check ?on.exit. This function makes it possible to restore options before exiting a function even if the function breaks. Therefore it needs to be called immediately after the option change within a function.  
+
+Please always make sure to reset to user's options(), working directory or par() after you changed it in examples and vignettes and demos.  
+e.g.:  
+oldpar <- par(mfrow = c(1,2))  
+...  
+par(oldpar)  
+
+:::
+
 Ideally, the user's options are not changed at all. If they really have to be altered, restoring the previous values of user options is mandatory for CRAN packages. 
 The reason for this rule is this line stated in the [CRAN Repository Policy](https://cran.r-project.org/web/packages/policies.html):