Skip to content

Commit 89222f6

Browse files
Baltmann01Baltmann01
authored
Merge pull request #66 from r-devel/CRAN-comments
Cran comments
2 parents 97bb232 + 8a2981b commit 89222f6

File tree

7 files changed

+154
-14
lines changed

7 files changed

+154
-14
lines changed

‎_freeze/code_issues/execute-results/html.json‎

Lines changed: 3 additions & 5 deletions
Large diffs are not rendered by default.

‎_freeze/description_issues/execute-results/html.json‎

Lines changed: 3 additions & 5 deletions
Large diffs are not rendered by default.

‎_freeze/preface/execute-results/html.json‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
{
2-
"hash": "5a6e0e21e8e8168e1c9927b155b84912",
2+
"hash": "293c910c7cd0ac1ff3a83c02c6abe6fa",
33
"result": {
44
"engine": "knitr",
5-
"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",
6-
"supporting": [],
5+
"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",
6+
"supporting": [
7+
"preface_files"
8+
],
79
"filters": [
810
"rmarkdown/pagebreak.lua"
911
],

‎code_issues.qmd‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,12 @@ Change the abbreviation to the full words or use a different variable name.
1717

1818
### Details
1919

20+
::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true}
21+
22+
Please write TRUE and FALSE instead of T and F. Please don't use "T" or "F" as vector names.
23+
24+
:::
25+
2026
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`.
2127

2228
### Examples
@@ -55,6 +61,12 @@ Remove the code that sets the seed. If you want to set it specifically in your f
5561

5662
### Details
5763

64+
::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true}
65+
66+
Please do not set a seed to a specific number within a function.
67+
68+
:::
69+
5870
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.
5971

6072
```{r, eval = FALSE}
@@ -91,6 +103,14 @@ You are using functions, like `print()` or `cat()`, to print unsuppressable outp
91103
Change `print()`/`cat()` to `message()`, `warning()`, `stop()`, or wrap them in `if(verbose){}`.
92104

93105
### Details
106+
107+
::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true}
108+
109+
You write information messages to the console that cannot be easily suppressed.
110+
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)
111+
112+
:::
113+
94114
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.
95115

96116
:::{.callout-note}
@@ -151,6 +171,26 @@ Reset the changed options, in your functions by using [`on.exit()`](https://stat
151171

152172
### Details
153173

174+
::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true}
175+
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.
176+
e.g.:
177+
...
178+
oldpar <- par(no.readonly = TRUE) # code line i
179+
on.exit(par(oldpar)) # code line i + 1
180+
...
181+
par(mfrow=c(2,2)) # somewhere after
182+
...
183+
e.g.:
184+
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.
185+
186+
Please always make sure to reset to user's options(), working directory or par() after you changed it in examples and vignettes and demos.
187+
e.g.:
188+
oldpar <- par(mfrow = c(1,2))
189+
...
190+
par(oldpar)
191+
192+
:::
193+
154194
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.
155195
The reason for this rule is this line stated in the [CRAN Repository Policy](https://cran.r-project.org/web/packages/policies.html):
156196

0 commit comments

Comments
 (0)