From e3a483aa94a61fa6483d9a935e0d93f087fb9df0 Mon Sep 17 00:00:00 2001 From: Baltmann01 Date: Fri, 8 Nov 2024 17:00:38 +0100 Subject: [PATCH 1/5] description issues --- .../execute-results/html.json | 8 +-- _freeze/preface/execute-results/html.json | 8 ++- description_issues.qmd | 65 +++++++++++++++++++ 3 files changed, 73 insertions(+), 8 deletions(-) diff --git a/_freeze/description_issues/execute-results/html.json b/_freeze/description_issues/execute-results/html.json index 3ef1e0f..8511007 100644 --- a/_freeze/description_issues/execute-results/html.json +++ b/_freeze/description_issues/execute-results/html.json @@ -1,11 +1,9 @@ { - "hash": "454c793487682193cec36c31a714fb64", + "hash": "7fb8115f922aa35fe571f830918b314d", "result": { "engine": "knitr", - "markdown": "---\ntitle: \"DESCRIPTION file Issues\"\nformat: \n html:\n css: style.css\n---\n\n\n\n\n\n\n\n# Formatting Software Names\n\n## Problem\n\nThe automatic spell check has flagged a software name as incorrect and results in a NOTE.\n\n## Solution\n\nAll references to names of software, packages and API names in the description section of the DESCRIPTION file should be wrapped in single quotes. e.g.: 'ggplot2', 'Python', etc.\n\n### Details\n\nWords in single quotes are not flagged by the automatic spell check and may be used when appropriate to include references to software names **only**.\n\nThe description section in the [DESCRIPTION file](https://github.com/tidyverse/readr/blob/main/DESCRIPTION) of the 'readr' package provides an example which uses single quotes around the package name and file extensions:\n\n``` \nDescription: The goal of 'readr' is to provide a fast and friendly way to\n read rectangular data (like 'csv', 'tsv', and 'fwf'). It is designed\n to flexibly parse many types of data found in the wild, while still\n cleanly failing when data unexpectedly changes.\n```\n\n------------------------------------------------------------------------\n\n\n# Explaining Acronyms\n\n## Problem\n\nYou are using acronyms in your DESCRIPTION file or they are flagged by the automatic spell check.\n\n## Solution\n\nDocument all non-obvious acronyms in the [cran-comments.md](https://usethis.r-lib.org/reference/use_cran_comments.html) file to facilitate the CRAN team review.\n\n### Details\n\nMost acronyms that are not widely known should be explained. For example, you don’t have to explain *OLS*, *SEO*, or *DNA* but explanations should be provided for: *MEFM* or *OCCDS*. If you are unsure of the acronyms common knowledge, please document all acronyms in the package.\n\n\n------------------------------------------------------------------------\n\n\n# LICENSE files\n\n## Problem\n\nSome licenses do not need to be added verbatim, instead they are referenced in the DESCRIPTION file and the CRAN template is added to the package. You can find the template at the [CRAN website](https://cran.r-project.org/web/licenses/).\n\n## Solution\n\nRemove the reference `+ file LICENSE` and delete the LICENSE file.\n\n### Details\n\nMost licenses don’t need an additional file as these are part of R. The list of which licenses that do require an additional file can be accessed within _R_ by searching for **Note: this is a template, needs + file LICENSE**:\n\n```r\npath_licenses <- list.files(path = R.home(), \"license.db\", full.names = TRUE, recursive = TRUE)\nlicenses_doc <- as.data.frame(read.dcf(path_licenses))\n```\n\nIf an additional file is needed, it should only specify the **author** and **year** for a MIT file or **year**, **copyright holder**, and **organization** for a BSD file. \n\n::: callout-tip\n## Tip\n\nLicenses should be FOSS, or allowed by [R](https://svn.r-project.org/R/trunk/share/licenses/license.db). \n\n:::\n\n\n------------------------------------------------------------------------\n\n# Title Case\n\n## Problem\n\nThe package Title field in the DESCRIPTION file is not in Title Case and the first letter of some or all of the words in the title are lowercase.\n\n## Solution\n\nThe package Title field in the DESCRIPTION file must be in Title Case, except words like \"a\", \"the\" or \"of\".\n\n### Details\n\nDetermining Title Case automatically can be challenging due to word significance being only known by the package author. The function `toTitleCase()` can assist with transforming sentences into Title Case from the 'tools' package.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\ntools::toTitleCase(\"web application framework for R\")\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] \"Web Application Framework for R\"\n```\n\n\n:::\n:::\n\n\n\n\n\n\n\n::: callout-note\nThere are some exceptions to using Title Case for quoting longer works like book titles and shorter works like [research papers](https://www.scribbr.com/academic-writing/title-case/#:~:text=In%20title%20case%2C%20the%20first,title%2C%20subtitle%2C%20or%20heading.). \n\nIt is also not recommended to [mention package names](https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#The-DESCRIPTION-file) in the Title.\n:::\n\n------------------------------------------------------------------------\n\n# Using Authors@R\n\n\n## Problem\n\nYou have not properly declared the authors, maintainers and copyright holders in the `Authors@R` section of the DESCRIPTION file.\n\n## Solution\n\nAdd the `Authors@R` field in the DESCRIPTION file. \n\n\n### Details\n\nYou can find more roles in the help documentation by running `?utils::person`. Make sure the provided email address is actively monitored, as it will be the primary point of contact with CRAN for future updates and fixes.\n\n\n\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nAuthors@R: person(\"Jane\", \"Smith\", email = \"chef@cran-cookbook.com\",\n role = c(\"aut\", \"cre\"), ORCID = \"\")\n```\n:::\n\n\n\n\n\n\n\n\n::: callout-note\n\nThe Maintainer and Author fields are automatically generated, so you don't need to add them manually.\n\nIf your package uses the older approach of specifying Maintainer and Author separately in the DESCRIPTION file, it won’t be rejected for that reason alone. However, this method is discouraged, and any manual modifications that differ from the auto-generated fields will result in automatic rejection by CRAN.\n\n:::\n\n\n------------------------------------------------------------------------\n\n# References\n\n## Problem\n\nThe reference link in the Description field is incorrectly formatted or isn't clickable.\n\n## Solution\n\nRemove the space after or to enable the reference link.\nWrite the reference in the form: Authors (year) .\n\n\n### Details\n\nIdeally, each package should include at least one reference in the description text to help users further explore the theory behind the package. These references should be formatted as shown in the ['Rcpp'](https://github.com/RcppCore/Rcpp/blob/master/DESCRIPTION#L21-L29) package:\n\n```\nDescription: The 'Rcpp' package provides R functions as well as C++ classes which\n offer a seamless integration of R and C++. Many R data types and objects can be\n mapped back and forth to C++ equivalents which facilitates both writing of new\n code as well as easier integration of third-party libraries. Documentation\n about 'Rcpp' is provided by several vignettes included in this package, via the\n 'Rcpp Gallery' site at , the paper by Eddelbuettel and\n Francois (2011, ), the book by Eddelbuettel (2013,\n ) and the paper by Eddelbuettel and Balamuta (2018,\n ); see 'citation(\"Rcpp\")' for details.\n```\n\n\n::: callout-tip\n\nIncluding a reference in the Description field is optional, and your package will not be archived if one is missing. You can also use the [cran-comments.md](https://usethis.r-lib.org/reference/use_cran_comments.html) file to provide additional references or information.\n\n:::\n", - "supporting": [ - "description_issues_files" - ], + "markdown": "---\ntitle: \"DESCRIPTION file Issues\"\nformat: \n html:\n css: style.css\n---\n\n\n\n\n# Formatting Software Names\n\n## Problem\n\nThe automatic spell check has flagged a software name as incorrect and results in a NOTE.\n\n## Solution\n\nAll references to names of software, packages and API names in the description section of the DESCRIPTION file should be wrapped in single quotes. e.g.: 'ggplot2', 'Python', etc.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nPlease always write package names, software names and API (application programming interface) names in single quotes in title and description.\ne.g: --> 'python'\n\nPlease note that package names are case sensitive.\n\n:::\n\nWords in single quotes are not flagged by the automatic spell check and may be used when appropriate to include references to software names **only**.\n\nThe description section in the [DESCRIPTION file](https://github.com/tidyverse/readr/blob/main/DESCRIPTION) of the 'readr' package provides an example which uses single quotes around the package name and file extensions:\n\n``` \nDescription: The goal of 'readr' is to provide a fast and friendly way to\n read rectangular data (like 'csv', 'tsv', and 'fwf'). It is designed\n to flexibly parse many types of data found in the wild, while still\n cleanly failing when data unexpectedly changes.\n```\n\n------------------------------------------------------------------------\n\n\n# Explaining Acronyms\n\n## Problem\n\nYou are using acronyms in your DESCRIPTION file or they are flagged by the automatic spell check.\n\n## Solution\n\nDocument all non-obvious acronyms in the [cran-comments.md](https://usethis.r-lib.org/reference/use_cran_comments.html) file to facilitate the CRAN team review.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nPlease always explain all acronyms in the description text.\n\n:::\n\nMost acronyms that are not widely known should be explained. For example, you don’t have to explain *OLS*, *SEO*, or *DNA* but explanations should be provided for: *MEFM* or *OCCDS*. If you are unsure of the acronyms common knowledge, please document all acronyms in the package.\n\n\n------------------------------------------------------------------------\n\n\n# LICENSE files\n\n## Problem\n\nSome licenses do not need to be added verbatim, instead they are referenced in the DESCRIPTION file and the CRAN template is added to the package. You can find the template at the [CRAN website](https://cran.r-project.org/web/licenses/).\n\n## Solution\n\nRemove the reference `+ file LICENSE` and delete the LICENSE file.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nThe LICENSE file is only needed if you have additional restrictions to the license which you have not? In that case omit the file and its reference in the DESCRIPTION file.\n\nLicense components with restrictions and base license permitting such:\nGPL-3 + file LICENSE\n\nWe do not need \"+ file LICENSE\" and the file as these are part of R. This is only needed in case of attribution requirements or other possible restrictions. Hence please omit it.\n\n:::\n\nMost licenses don’t need an additional file as these are part of R. The list of which licenses that do require an additional file can be accessed within _R_ by searching for **Note: this is a template, needs + file LICENSE**:\n\n```r\npath_licenses <- list.files(path = R.home(), \"license.db\", full.names = TRUE, recursive = TRUE)\nlicenses_doc <- as.data.frame(read.dcf(path_licenses))\n```\n\nIf an additional file is needed, it should only specify the **author** and **year** for a MIT file or **year**, **copyright holder**, and **organization** for a BSD file. \n\n::: callout-tip\n## Tip\n\nLicenses should be FOSS, or allowed by [R](https://svn.r-project.org/R/trunk/share/licenses/license.db). \n\n:::\n\n\n------------------------------------------------------------------------\n\n# Title Case\n\n## Problem\n\nThe package Title field in the DESCRIPTION file is not in Title Case and the first letter of some or all of the words in the title are lowercase.\n\n## Solution\n\nThe package Title field in the DESCRIPTION file must be in Title Case, except words like \"a\", \"the\" or \"of\".\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nThe Title field should be in title case. Current version is: \n'This is my title'\n\nIn title case that is: \n'This is My Title'\n\n:::\n\nDetermining Title Case automatically can be challenging due to word significance being only known by the package author. The function `toTitleCase()` can assist with transforming sentences into Title Case from the 'tools' package.\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\ntools::toTitleCase(\"web application framework for R\")\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] \"Web Application Framework for R\"\n```\n\n\n:::\n:::\n\n\n\n\n::: callout-note\nThere are some exceptions to using Title Case for quoting longer works like book titles and shorter works like [research papers](https://www.scribbr.com/academic-writing/title-case/#:~:text=In%20title%20case%2C%20the%20first,title%2C%20subtitle%2C%20or%20heading.). \n\nIt is also not recommended to [mention package names](https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#The-DESCRIPTION-file) in the Title.\n:::\n\n------------------------------------------------------------------------\n\n# Using Authors@R\n\n\n## Problem\n\nYou have not properly declared the authors, maintainers and copyright holders in the `Authors@R` section of the DESCRIPTION file.\n\n## Solution\n\nAdd the `Authors@R` field in the DESCRIPTION file. \n\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nAuthor field differs from that derived from Authors@R.\n\nNo Authors@R field in DESCRIPTION.\n Please add one, modifying\n Authors@R: c(person(given = \"Alice\",\n family = \"Developer\",\n role = c(\"aut\", \"cre\"),\n email = \"alice.developer@some.domain.net\"),\n person(given = \"Bob\",\n family = \"Dev\",\n role = \"aut\"),\n )\n as necessary.\n\n:::\n\nYou can find more roles in the help documentation by running `?utils::person`. Make sure the provided email address is actively monitored, as it will be the primary point of contact with CRAN for future updates and fixes.\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nAuthors@R: person(\"Jane\", \"Smith\", email = \"chef@cran-cookbook.com\",\n role = c(\"aut\", \"cre\"), ORCID = \"\")\n```\n:::\n\n\n\n\n\n::: callout-note\n\nThe Maintainer and Author fields are automatically generated, so you don't need to add them manually.\n\nIf your package uses the older approach of specifying Maintainer and Author separately in the DESCRIPTION file, it won’t be rejected for that reason alone. However, this method is discouraged, and any manual modifications that differ from the auto-generated fields will result in automatic rejection by CRAN.\n\n:::\n\n\n------------------------------------------------------------------------\n\n# References\n\n## Problem\n\nThe reference link in the Description field is incorrectly formatted or isn't clickable.\n\n## Solution\n\nRemove the space after or to enable the reference link.\nWrite the reference in the form: Authors (year) .\n\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nIf there are references describing the methods in your package, please add these in the description field of your DESCRIPTION file in the form\nauthors (year) \nauthors (year, ISBN:...)\nor if those are not available: \nwith no space after 'doi:', 'https:' and angle brackets for auto-linking. (If you want to add a title as well please put it in quotes: \"Title\")\n\n:::\n\n\nIdeally, each package should include at least one reference in the description text to help users further explore the theory behind the package. These references should be formatted as shown in the ['Rcpp'](https://github.com/RcppCore/Rcpp/blob/master/DESCRIPTION#L21-L29) package:\n\n```\nDescription: The 'Rcpp' package provides R functions as well as C++ classes which\n offer a seamless integration of R and C++. Many R data types and objects can be\n mapped back and forth to C++ equivalents which facilitates both writing of new\n code as well as easier integration of third-party libraries. Documentation\n about 'Rcpp' is provided by several vignettes included in this package, via the\n 'Rcpp Gallery' site at , the paper by Eddelbuettel and\n Francois (2011, ), the book by Eddelbuettel (2013,\n ) and the paper by Eddelbuettel and Balamuta (2018,\n ); see 'citation(\"Rcpp\")' for details.\n```\n\n\n::: callout-tip\n\nIncluding a reference in the Description field is optional, and your package will not be archived if one is missing. You can also use the [cran-comments.md](https://usethis.r-lib.org/reference/use_cran_comments.html) file to provide additional references or information.\n\n:::\n", + "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" ], diff --git a/_freeze/preface/execute-results/html.json b/_freeze/preface/execute-results/html.json index 7d1bc76..df8165a 100644 --- a/_freeze/preface/execute-results/html.json +++ b/_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 \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\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 . 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 \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\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 . 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" ], diff --git a/description_issues.qmd b/description_issues.qmd index 9497b2b..821cd45 100644 --- a/description_issues.qmd +++ b/description_issues.qmd @@ -17,6 +17,15 @@ All references to names of software, packages and API names in the description s ### Details +::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true} + +Please always write package names, software names and API (application programming interface) names in single quotes in title and description. +e.g: --> 'python' + +Please note that package names are case sensitive. + +::: + Words in single quotes are not flagged by the automatic spell check and may be used when appropriate to include references to software names **only**. The description section in the [DESCRIPTION file](https://github.com/tidyverse/readr/blob/main/DESCRIPTION) of the 'readr' package provides an example which uses single quotes around the package name and file extensions: @@ -43,6 +52,12 @@ Document all non-obvious acronyms in the [cran-comments.md](https://usethis.r-li ### Details +::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true} + +Please always explain all acronyms in the description text. + +::: + Most acronyms that are not widely known should be explained. For example, you don’t have to explain *OLS*, *SEO*, or *DNA* but explanations should be provided for: *MEFM* or *OCCDS*. If you are unsure of the acronyms common knowledge, please document all acronyms in the package. @@ -61,6 +76,17 @@ Remove the reference `+ file LICENSE` and delete the LICENSE file. ### Details +::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true} + +The LICENSE file is only needed if you have additional restrictions to the license which you have not? In that case omit the file and its reference in the DESCRIPTION file. + +License components with restrictions and base license permitting such: +GPL-3 + file LICENSE + +We do not need "+ file LICENSE" and the file as these are part of R. This is only needed in case of attribution requirements or other possible restrictions. Hence please omit it. + +::: + Most licenses don’t need an additional file as these are part of R. The list of which licenses that do require an additional file can be accessed within _R_ by searching for **Note: this is a template, needs + file LICENSE**: ```r @@ -92,6 +118,16 @@ The package Title field in the DESCRIPTION file must be in Title Case, except wo ### Details +::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true} + +The Title field should be in title case. Current version is: +'This is my title' + +In title case that is: +'This is My Title' + +::: + Determining Title Case automatically can be challenging due to word significance being only known by the package author. The function `toTitleCase()` can assist with transforming sentences into Title Case from the 'tools' package. ```{r} @@ -120,6 +156,24 @@ Add the `Authors@R` field in the DESCRIPTION file. ### Details +::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true} + +Author field differs from that derived from Authors@R. + +No Authors@R field in DESCRIPTION. + Please add one, modifying + Authors@R: c(person(given = "Alice", + family = "Developer", + role = c("aut", "cre"), + email = "alice.developer@some.domain.net"), + person(given = "Bob", + family = "Dev", + role = "aut"), + ) + as necessary. + +::: + You can find more roles in the help documentation by running `?utils::person`. Make sure the provided email address is actively monitored, as it will be the primary point of contact with CRAN for future updates and fixes. ```{r, eval=FALSE} @@ -153,6 +207,17 @@ Write the reference in the form: Authors (year) . ### Details +::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true} + +If there are references describing the methods in your package, please add these in the description field of your DESCRIPTION file in the form +authors (year) +authors (year, ISBN:...) +or if those are not available: +with no space after 'doi:', 'https:' and angle brackets for auto-linking. (If you want to add a title as well please put it in quotes: "Title") + +::: + + Ideally, each package should include at least one reference in the description text to help users further explore the theory behind the package. These references should be formatted as shown in the ['Rcpp'](https://github.com/RcppCore/Rcpp/blob/master/DESCRIPTION#L21-L29) package: ``` From 4b33883f6d40242a9e0c427dc46244a8c3c27c40 Mon Sep 17 00:00:00 2001 From: Baltmann01 Date: Fri, 8 Nov 2024 17:04:43 +0100 Subject: [PATCH 2/5] Finished Description --- .../execute-results/html.json | 4 +-- description_issues.qmd | 30 +++++++++---------- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/_freeze/description_issues/execute-results/html.json b/_freeze/description_issues/execute-results/html.json index 8511007..dca2f90 100644 --- a/_freeze/description_issues/execute-results/html.json +++ b/_freeze/description_issues/execute-results/html.json @@ -1,8 +1,8 @@ { - "hash": "7fb8115f922aa35fe571f830918b314d", + "hash": "be4833313903244dd8388b97eba498fe", "result": { "engine": "knitr", - "markdown": "---\ntitle: \"DESCRIPTION file Issues\"\nformat: \n html:\n css: style.css\n---\n\n\n\n\n# Formatting Software Names\n\n## Problem\n\nThe automatic spell check has flagged a software name as incorrect and results in a NOTE.\n\n## Solution\n\nAll references to names of software, packages and API names in the description section of the DESCRIPTION file should be wrapped in single quotes. e.g.: 'ggplot2', 'Python', etc.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nPlease always write package names, software names and API (application programming interface) names in single quotes in title and description.\ne.g: --> 'python'\n\nPlease note that package names are case sensitive.\n\n:::\n\nWords in single quotes are not flagged by the automatic spell check and may be used when appropriate to include references to software names **only**.\n\nThe description section in the [DESCRIPTION file](https://github.com/tidyverse/readr/blob/main/DESCRIPTION) of the 'readr' package provides an example which uses single quotes around the package name and file extensions:\n\n``` \nDescription: The goal of 'readr' is to provide a fast and friendly way to\n read rectangular data (like 'csv', 'tsv', and 'fwf'). It is designed\n to flexibly parse many types of data found in the wild, while still\n cleanly failing when data unexpectedly changes.\n```\n\n------------------------------------------------------------------------\n\n\n# Explaining Acronyms\n\n## Problem\n\nYou are using acronyms in your DESCRIPTION file or they are flagged by the automatic spell check.\n\n## Solution\n\nDocument all non-obvious acronyms in the [cran-comments.md](https://usethis.r-lib.org/reference/use_cran_comments.html) file to facilitate the CRAN team review.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nPlease always explain all acronyms in the description text.\n\n:::\n\nMost acronyms that are not widely known should be explained. For example, you don’t have to explain *OLS*, *SEO*, or *DNA* but explanations should be provided for: *MEFM* or *OCCDS*. If you are unsure of the acronyms common knowledge, please document all acronyms in the package.\n\n\n------------------------------------------------------------------------\n\n\n# LICENSE files\n\n## Problem\n\nSome licenses do not need to be added verbatim, instead they are referenced in the DESCRIPTION file and the CRAN template is added to the package. You can find the template at the [CRAN website](https://cran.r-project.org/web/licenses/).\n\n## Solution\n\nRemove the reference `+ file LICENSE` and delete the LICENSE file.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nThe LICENSE file is only needed if you have additional restrictions to the license which you have not? In that case omit the file and its reference in the DESCRIPTION file.\n\nLicense components with restrictions and base license permitting such:\nGPL-3 + file LICENSE\n\nWe do not need \"+ file LICENSE\" and the file as these are part of R. This is only needed in case of attribution requirements or other possible restrictions. Hence please omit it.\n\n:::\n\nMost licenses don’t need an additional file as these are part of R. The list of which licenses that do require an additional file can be accessed within _R_ by searching for **Note: this is a template, needs + file LICENSE**:\n\n```r\npath_licenses <- list.files(path = R.home(), \"license.db\", full.names = TRUE, recursive = TRUE)\nlicenses_doc <- as.data.frame(read.dcf(path_licenses))\n```\n\nIf an additional file is needed, it should only specify the **author** and **year** for a MIT file or **year**, **copyright holder**, and **organization** for a BSD file. \n\n::: callout-tip\n## Tip\n\nLicenses should be FOSS, or allowed by [R](https://svn.r-project.org/R/trunk/share/licenses/license.db). \n\n:::\n\n\n------------------------------------------------------------------------\n\n# Title Case\n\n## Problem\n\nThe package Title field in the DESCRIPTION file is not in Title Case and the first letter of some or all of the words in the title are lowercase.\n\n## Solution\n\nThe package Title field in the DESCRIPTION file must be in Title Case, except words like \"a\", \"the\" or \"of\".\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nThe Title field should be in title case. Current version is: \n'This is my title'\n\nIn title case that is: \n'This is My Title'\n\n:::\n\nDetermining Title Case automatically can be challenging due to word significance being only known by the package author. The function `toTitleCase()` can assist with transforming sentences into Title Case from the 'tools' package.\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\ntools::toTitleCase(\"web application framework for R\")\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] \"Web Application Framework for R\"\n```\n\n\n:::\n:::\n\n\n\n\n::: callout-note\nThere are some exceptions to using Title Case for quoting longer works like book titles and shorter works like [research papers](https://www.scribbr.com/academic-writing/title-case/#:~:text=In%20title%20case%2C%20the%20first,title%2C%20subtitle%2C%20or%20heading.). \n\nIt is also not recommended to [mention package names](https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#The-DESCRIPTION-file) in the Title.\n:::\n\n------------------------------------------------------------------------\n\n# Using Authors@R\n\n\n## Problem\n\nYou have not properly declared the authors, maintainers and copyright holders in the `Authors@R` section of the DESCRIPTION file.\n\n## Solution\n\nAdd the `Authors@R` field in the DESCRIPTION file. \n\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nAuthor field differs from that derived from Authors@R.\n\nNo Authors@R field in DESCRIPTION.\n Please add one, modifying\n Authors@R: c(person(given = \"Alice\",\n family = \"Developer\",\n role = c(\"aut\", \"cre\"),\n email = \"alice.developer@some.domain.net\"),\n person(given = \"Bob\",\n family = \"Dev\",\n role = \"aut\"),\n )\n as necessary.\n\n:::\n\nYou can find more roles in the help documentation by running `?utils::person`. Make sure the provided email address is actively monitored, as it will be the primary point of contact with CRAN for future updates and fixes.\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nAuthors@R: person(\"Jane\", \"Smith\", email = \"chef@cran-cookbook.com\",\n role = c(\"aut\", \"cre\"), ORCID = \"\")\n```\n:::\n\n\n\n\n\n::: callout-note\n\nThe Maintainer and Author fields are automatically generated, so you don't need to add them manually.\n\nIf your package uses the older approach of specifying Maintainer and Author separately in the DESCRIPTION file, it won’t be rejected for that reason alone. However, this method is discouraged, and any manual modifications that differ from the auto-generated fields will result in automatic rejection by CRAN.\n\n:::\n\n\n------------------------------------------------------------------------\n\n# References\n\n## Problem\n\nThe reference link in the Description field is incorrectly formatted or isn't clickable.\n\n## Solution\n\nRemove the space after or to enable the reference link.\nWrite the reference in the form: Authors (year) .\n\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nIf there are references describing the methods in your package, please add these in the description field of your DESCRIPTION file in the form\nauthors (year) \nauthors (year, ISBN:...)\nor if those are not available: \nwith no space after 'doi:', 'https:' and angle brackets for auto-linking. (If you want to add a title as well please put it in quotes: \"Title\")\n\n:::\n\n\nIdeally, each package should include at least one reference in the description text to help users further explore the theory behind the package. These references should be formatted as shown in the ['Rcpp'](https://github.com/RcppCore/Rcpp/blob/master/DESCRIPTION#L21-L29) package:\n\n```\nDescription: The 'Rcpp' package provides R functions as well as C++ classes which\n offer a seamless integration of R and C++. Many R data types and objects can be\n mapped back and forth to C++ equivalents which facilitates both writing of new\n code as well as easier integration of third-party libraries. Documentation\n about 'Rcpp' is provided by several vignettes included in this package, via the\n 'Rcpp Gallery' site at , the paper by Eddelbuettel and\n Francois (2011, ), the book by Eddelbuettel (2013,\n ) and the paper by Eddelbuettel and Balamuta (2018,\n ); see 'citation(\"Rcpp\")' for details.\n```\n\n\n::: callout-tip\n\nIncluding a reference in the Description field is optional, and your package will not be archived if one is missing. You can also use the [cran-comments.md](https://usethis.r-lib.org/reference/use_cran_comments.html) file to provide additional references or information.\n\n:::\n", + "markdown": "---\ntitle: \"DESCRIPTION file Issues\"\nformat: \n html:\n css: style.css\n---\n\n\n\n\n# Formatting Software Names\n\n## Problem\n\nThe automatic spell check has flagged a software name as incorrect and results in a NOTE.\n\n## Solution\n\nAll references to names of software, packages and API names in the description section of the DESCRIPTION file should be wrapped in single quotes. e.g.: 'ggplot2', 'Python', etc.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nPlease always write package names, software names and API (application programming interface) names in single quotes in title and description.\ne.g: --> 'python'\n\nPlease note that package names are case sensitive.\n\n:::\n\nWords in single quotes are not flagged by the automatic spell check and may be used when appropriate to include references to software names **only**.\n\nThe description section in the [DESCRIPTION file](https://github.com/tidyverse/readr/blob/main/DESCRIPTION) of the 'readr' package provides an example which uses single quotes around the package name and file extensions:\n\n``` \nDescription: The goal of 'readr' is to provide a fast and friendly way to\n read rectangular data (like 'csv', 'tsv', and 'fwf'). It is designed\n to flexibly parse many types of data found in the wild, while still\n cleanly failing when data unexpectedly changes.\n```\n\n------------------------------------------------------------------------\n\n\n# Explaining Acronyms\n\n## Problem\n\nYou are using acronyms in your DESCRIPTION file or they are flagged by the automatic spell check.\n\n## Solution\n\nDocument all non-obvious acronyms in the [cran-comments.md](https://usethis.r-lib.org/reference/use_cran_comments.html) file to facilitate the CRAN team review.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nPlease always explain all acronyms in the description text.\n\n:::\n\nMost acronyms that are not widely known should be explained. For example, you don’t have to explain *OLS*, *SEO*, or *DNA* but explanations should be provided for: *MEFM* or *OCCDS*. If you are unsure of the acronyms common knowledge, please document all acronyms in the package.\n\n\n------------------------------------------------------------------------\n\n\n# LICENSE files\n\n## Problem\n\nSome licenses do not need to be added verbatim, instead they are referenced in the DESCRIPTION file and the CRAN template is added to the package. You can find the template at the [CRAN website](https://cran.r-project.org/web/licenses/).\n\n## Solution\n\nRemove the reference `+ file LICENSE` and delete the LICENSE file.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nThe LICENSE file is only needed if you have additional restrictions to the license which you have not? In that case omit the file and its reference in the DESCRIPTION file.\n\nLicense components with restrictions and base license permitting such:\nGPL-3 + file LICENSE\n\nWe do not need \"+ file LICENSE\" and the file as these are part of R. This is only needed in case of attribution requirements or other possible restrictions. Hence please omit it.\n\n:::\n\nMost licenses don’t need an additional file as these are part of R. The list of which licenses that do require an additional file can be accessed within _R_ by searching for **Note: this is a template, needs + file LICENSE**:\n\n```r\npath_licenses <- list.files(path = R.home(), \"license.db\", full.names = TRUE, recursive = TRUE)\nlicenses_doc <- as.data.frame(read.dcf(path_licenses))\n```\n\nIf an additional file is needed, it should only specify the **author** and **year** for a MIT file or **year**, **copyright holder**, and **organization** for a BSD file. \n\n::: callout-tip\n## Tip\n\nLicenses should be FOSS, or allowed by [R](https://svn.r-project.org/R/trunk/share/licenses/license.db). \n\n:::\n\n\n------------------------------------------------------------------------\n\n# Title Case\n\n## Problem\n\nThe package Title field in the DESCRIPTION file is not in Title Case and the first letter of some or all of the words in the title are lowercase.\n\n## Solution\n\nThe package Title field in the DESCRIPTION file must be in Title Case, except words like \"a\", \"the\" or \"of\".\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nThe Title field should be in title case. Current version is: \n'This is my title'\n\nIn title case that is: \n'This is My Title'\n\n:::\n\nDetermining Title Case automatically can be challenging due to word significance being only known by the package author. The function `toTitleCase()` can assist with transforming sentences into Title Case from the 'tools' package.\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\ntools::toTitleCase(\"web application framework for R\")\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] \"Web Application Framework for R\"\n```\n\n\n:::\n:::\n\n\n\n\n::: callout-note\nThere are some exceptions to using Title Case for quoting longer works like book titles and shorter works like [research papers](https://www.scribbr.com/academic-writing/title-case/#:~:text=In%20title%20case%2C%20the%20first,title%2C%20subtitle%2C%20or%20heading.). \n\nIt is also not recommended to [mention package names](https://cran.r-project.org/doc/manuals/r-devel/R-exts.html#The-DESCRIPTION-file) in the Title.\n:::\n\n------------------------------------------------------------------------\n\n# Using Authors@R\n\n\n## Problem\n\nYou have not properly declared the authors, maintainers and copyright holders in the `Authors@R` section of the DESCRIPTION file.\n\n## Solution\n\nAdd the `Authors@R` field in the DESCRIPTION file. \n\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nAuthor field differs from that derived from Authors@R.\n\nNo Authors@R field in DESCRIPTION. \n  Please add one, modifying \n    Authors@R: c(person(given = \"Alice\", \n      family = \"Developer\", \n      role = c(\"aut\", \"cre\"), \n      email = \"alice.developer@some.domain.net\"), \n    person(given = \"Bob\", \n      family = \"Dev\", \n      role = \"aut\"), \n    ) \n  as necessary.\n\n:::\n\nYou can find more roles in the help documentation by running `?utils::person`. Make sure the provided email address is actively monitored, as it will be the primary point of contact with CRAN for future updates and fixes.\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nAuthors@R: person(\"Jane\", \"Smith\", email = \"chef@cran-cookbook.com\",\n role = c(\"aut\", \"cre\"), ORCID = \"\")\n```\n:::\n\n\n\n\n\n::: callout-note\n\nThe Maintainer and Author fields are automatically generated, so you don't need to add them manually.\n\nIf your package uses the older approach of specifying Maintainer and Author separately in the DESCRIPTION file, it won’t be rejected for that reason alone. However, this method is discouraged, and any manual modifications that differ from the auto-generated fields will result in automatic rejection by CRAN.\n\n:::\n\n\n------------------------------------------------------------------------\n\n# References\n\n## Problem\n\nThe reference link in the Description field is incorrectly formatted or isn't clickable.\n\n## Solution\n\nRemove the space after or to enable the reference link.\nWrite the reference in the form: Authors (year) .\n\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nIf there are references describing the methods in your package, please add these in the description field of your DESCRIPTION file in the form \nauthors (year) \nauthors (year, ISBN:...) \nor if those are not available: \nwith no space after 'doi:', 'https:' and angle brackets for auto-linking. (If you want to add a title as well please put it in quotes: \"Title\")\n\n:::\n\n\nIdeally, each package should include at least one reference in the description text to help users further explore the theory behind the package. These references should be formatted as shown in the ['Rcpp'](https://github.com/RcppCore/Rcpp/blob/master/DESCRIPTION#L21-L29) package:\n\n```\nDescription: The 'Rcpp' package provides R functions as well as C++ classes which\n offer a seamless integration of R and C++. Many R data types and objects can be\n mapped back and forth to C++ equivalents which facilitates both writing of new\n code as well as easier integration of third-party libraries. Documentation\n about 'Rcpp' is provided by several vignettes included in this package, via the\n 'Rcpp Gallery' site at , the paper by Eddelbuettel and\n Francois (2011, ), the book by Eddelbuettel (2013,\n ) and the paper by Eddelbuettel and Balamuta (2018,\n ); see 'citation(\"Rcpp\")' for details.\n```\n\n\n::: callout-tip\n\nIncluding a reference in the Description field is optional, and your package will not be archived if one is missing. You can also use the [cran-comments.md](https://usethis.r-lib.org/reference/use_cran_comments.html) file to provide additional references or information.\n\n:::\n", "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" diff --git a/description_issues.qmd b/description_issues.qmd index 821cd45..56683e2 100644 --- a/description_issues.qmd +++ b/description_issues.qmd @@ -160,17 +160,17 @@ Add the `Authors@R` field in the DESCRIPTION file. Author field differs from that derived from Authors@R. -No Authors@R field in DESCRIPTION. - Please add one, modifying - Authors@R: c(person(given = "Alice", - family = "Developer", - role = c("aut", "cre"), - email = "alice.developer@some.domain.net"), - person(given = "Bob", - family = "Dev", - role = "aut"), - ) - as necessary. +No Authors@R field in DESCRIPTION. +  Please add one, modifying +    Authors@R: c(person(given = "Alice", +      family = "Developer", +      role = c("aut", "cre"), +      email = "alice.developer@some.domain.net"), +    person(given = "Bob", +      family = "Dev", +      role = "aut"), +    ) +  as necessary. ::: @@ -209,10 +209,10 @@ Write the reference in the form: Authors (year) . ::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true} -If there are references describing the methods in your package, please add these in the description field of your DESCRIPTION file in the form -authors (year) -authors (year, ISBN:...) -or if those are not available: +If there are references describing the methods in your package, please add these in the description field of your DESCRIPTION file in the form +authors (year) +authors (year, ISBN:...) +or if those are not available: with no space after 'doi:', 'https:' and angle brackets for auto-linking. (If you want to add a title as well please put it in quotes: "Title") ::: From 69e73ab7fc087e1c913eda09b61c5c8253e241dd Mon Sep 17 00:00:00 2001 From: Baltmann01 Date: Fri, 8 Nov 2024 17:10:49 +0100 Subject: [PATCH 3/5] docs-issues --- docs_issues.qmd | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs_issues.qmd b/docs_issues.qmd index 81dde8c..032dec7 100644 --- a/docs_issues.qmd +++ b/docs_issues.qmd @@ -17,6 +17,12 @@ Often it is enough to simply add the missing `\value`-tags. If the function does ### Details +::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true} + +Please add \\value to .Rd files regarding exported methods and explain the functions results in the documentation. Please write about the structure of the output (class) and also what the output means. (If a function does not return a value, please document that too, e.g. \\value\{No return value, called for side effects\} or similar) + +::: + CRAN wants a `\value`-tag for every .Rd-file containing info about the structure of the output (class) and also what the output means. Adding a short explanation for each function helps users understand effects of the function call. This prevents unexpected outputs and helps to create a better workflow when using the function. @@ -51,6 +57,12 @@ Implement your changes in the corresponding .R-files instead of the .Rd-files. B ### Details +::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true} + +Since you are using 'roxygen2', please make sure to add a @return-tag in the corresponding .R-file and re-roxygenize() your .Rd-files. + +::: + If you decide to render your manuals with ['roxygen2'](https://cran.r-project.org/web/packages/roxygen2/index.html), the .Rd-files can be render using the function [`roxygenize()`](https://roxygen2.r-lib.org/reference/roxygenize.html). If changes are implemented directly in the .Rd-file, they will be overwritten during the next render. Similarly, changes in the 'roxygen2'-section of .R-files will not transfer to the .Rd-files without a re-rendering. ::: callout-tip From 822a2407af5fa7114a121a3c11dab76c19f09198 Mon Sep 17 00:00:00 2001 From: Baltmann01 Date: Fri, 8 Nov 2024 18:21:27 +0100 Subject: [PATCH 4/5] Code-issues --- _freeze/code_issues/execute-results/html.json | 8 ++-- code_issues.qmd | 40 +++++++++++++++++++ 2 files changed, 43 insertions(+), 5 deletions(-) diff --git a/_freeze/code_issues/execute-results/html.json b/_freeze/code_issues/execute-results/html.json index 9323e48..5c6cc5c 100644 --- a/_freeze/code_issues/execute-results/html.json +++ b/_freeze/code_issues/execute-results/html.json @@ -1,11 +1,9 @@ { - "hash": "20ff67a5ed220d0bd397a25806cead38", + "hash": "68662ed623996b100408c05013599cf8", "result": { "engine": "knitr", - "markdown": "---\ntitle: \"Code Issues\"\nformat: \n html:\n css: style.css\n---\n\n\n\n\n# `T`/`F` Instead of `TRUE`/`FALSE`\n\n## Problem\n\nYou are writing the abbreviated forms of `TRUE` and `FALSE`, `T` and `F` or you are using `T` or `F` as names.\n\n## Solution\n\nChange the abbreviation to the full words or use a different variable name.\n\n### Details\n\nIn 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`.\n\n### Examples\n\nThe first example shows that you cannot overwrite `TRUE`:\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nTRUE <- \"Not TRUE anymore\"\n```\n\n::: {.cell-output .cell-output-error}\n\n```\nError in TRUE <- \"Not TRUE anymore\": invalid (do_set) left-hand side to assignment\n```\n\n\n:::\n\n```{.r .cell-code}\nprint(TRUE)\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] TRUE\n```\n\n\n:::\n:::\n\n\n\n\nThis throws an error as `TRUE` is a reserved word and the value of `TRUE` does not change.\n\n`T` (and `F`) on the other hand can be set to a different value:\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nT <- \"Not TRUE anymore\"\n\nprint(T)\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] \"Not TRUE anymore\"\n```\n\n\n:::\n:::\n\n\n\n\nTo avoid any unexpected behaviors and inconsistencies, CRAN reviewers will ask you to write the reserved words, `TRUE` and `FALSE` instead of their abbreviated forms. For the same reason, `T` or `F` should not be used as variable names in your code, examples, tests or vignettes.\n\n--------------------------------------------------------------------\n\n# Setting a Specific Seed\n\n## Problem\n\nIn your functions, you are setting a the random seed to a specific number which cannot be changed.\n\n## Solution\n\nRemove the code that sets the seed. If you want to set it specifically in your functions, users should be able to set no seed if they want. \n\n### Details\n\nChanging 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. \n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nfunction(... , seed = NULL){\n if(!is.null(seed)){\n set.seed(seed)\n }\n \n #the rest of your function can be written here.\n \n}\n```\n:::\n\n\n\nThis allows users to avoid setting a seed if they change the argument to `NULL`. Ideally, the argument is already set to `NULL` per default. \n\n\n\n::: {.callout-note}\n\nIn your examples, vignettes, demos and tests setting a seed is not only allowed but also recommended to ensure reproducible results. \n\n:::\n\n-----------------------------------------------------------\n\n# Using `print()`/`cat()`\n\n## Problem\n\nYou are using functions, like `print()` or `cat()`, to print unsuppressable output to the console.\n\n## Solution\n\nChange `print()`/`cat()` to `message()`, `warning()`, `stop()`, or wrap them in `if(verbose){}`.\n\n### Details\nInformation 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. \n\n:::{.callout-note}\n\nPrinting in special functions like print, summary, interactive functions or methods for generic functions is accepted. \n\n:::\n\n\nTo allow users to suppress the console output CRAN recommends two different ways: \n\n * exchanging `cat()`/`print()` with other generics\n - [`message()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/message.html): for information messages and status updates \n - [`warning()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/warning.html): for warning, will print a \"Warning: \" before the output\n - [`stop()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/stop.html): for error messages, will print an \"Error: \" before the output and halt the execution\n \nThis allows to use functions like `suppressMessages()` to avoid unwanted output. \n\n * using an additional function argument\n - create one argument in your function to turn off the console output\n - CRAN suggests using `verbose`, other names are accepted\n \nThis example code shows the use of a `verbose` argument to allow users to suppress printing\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nfoo <- function(..., verbose = TRUE){\n # your code\n if(verbose){\n print(\"Whatever you want to say!\")\n }\n # your code\n}\n```\n:::\n\n\n\n\nFunctions can print per default, like the example above, as long as the printing can be turned off (here, by setting `verbose = FALSE`).\n\n:::{.callout-note}\n\n`print()` and `cat()` are not the only functions which can write output onto the console. The issue described in the recipe, also applies to the use of other printing function like `writeLines()`. \nIf you are using loggers to document your functions' process, make sure that users can set their log level such that not messages are displayed.\n\n:::\n\n\n\n---------------------------------------------------------\n\n# Change of Options, Graphical Parameters and Working Directory\n\n## Problem\n\nYou are changing the `par()`, `options()` or `setwd()` in your functions, examples, demos or vignettes without resetting them.\n\n## Solution \n\nReset the changed options, in your functions by using [`on.exit()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/on.exit.html) or in examples, demos and vignettes with an additional line of code after the example.\n\n### Details\n\nIdeally, 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. \nThe reason for this rule is this line stated in the [CRAN Repository Policy](https://cran.r-project.org/web/packages/policies.html):\n\n> The code and examples provided in a package should never do anything which might be regarded as malicious or anti-social.\n\nResetting options is therefore mainly a Quality-of-Life feature for users of your package.\n\nThere are different ways of resetting for functions, and examples, demos or vignettes which are recommended by CRAN. \n\nChanging `par()`, `options()` or `setwd()` all invisibly return the previous values and therefore these can be stored in variables using the assignment operator `<-` and later be restored by calling the variable name as argument in the respective function. \n\n\n**For functions**:\n\nWhen changing options inside one of your package functions, you can use [`on.exit()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/on.exit.html) for restoring. \n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nfoo <- function(x){\n \n # par():\n oldpar <- par(mfrow = c(2,2))\n on.exit(par(oldpar))\n \n # options():\n oldop <- options(digits = 3)\n on.exit(options(oldop))\n \n # setwd():\n oldwd <- setwd(\".\")\n on.exit(setwd(oldwd))\n \n # your code which requires a changed option\n \n}\n```\n:::\n\n\n\n\nThis will reset the `par()`, `options()` and `setwd()`. The use of [`on.exit()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/on.exit.html) 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. \nFor more information, call [`?on.exit()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/on.exit.html) in your console. \n\n\n**For demos, examples and vignettes**:\nSince no function is exited when changing options in examples, [`on.exit()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/on.exit.html) cannot be used. CRAN recommends the following way for restoring options:\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\noldpar <- par(mfrow = c(2,2))\n\n# your code which requires a changed option\n\npar(oldpar)\n```\n:::\n\n\n\n\nHere the code will only reset the options if the example runs without breaking. Therefore, try to keep the code between setting and resetting as concise as possible. Restoring the `options()` and `setwd()` can be done using the same principle as for `par()` shown above. \n\n:::{.callout-tip}\n\nIf you need to change more than one option in the same function, example, vignette or demo, you can use `oldpar <- par(no.readonly = TRUE)` or `oldop <- options()` to reset all parameters at once. Saving the entire \nNote, that for `par()` the `no.readonly` argument must be set to `TRUE` or else warnings will be produced.\n\n:::\n\n:::{.callout-note}\n\nThe issue described in the recipe, also applies to the use of other function which change some parameters persistently, like `Sys.setLanguage`. \n\n:::\n\n--------------------------\n\n# Writing Files and Directories to the Home Filespace\n\n## Problem\n\nYou are writing, either by default or within your examples, vignettes, or tests, to the user's home filespace, including the package directory and the current working directory (`getwd()`).\n\n\n## Solution \n\nOmit any default path in your functions and write to `tempdir()` in examples, vignettes or tests. \n\n\n### Details\n\n \n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nPlease ensure that your functions do not write by default or in your examples/vignettes/tests in the user's home filespace (including the package directory and getwd()). This is not allowed by CRAN policies. Please omit any default path in writing functions. In your examples/vignettes/tests you can write to tempdir().\n\n:::\n\nThe [CRAN Repository Policy](https://cran.r-project.org/web/packages/policies.html) states that:\n\n> The code and examples provided in a package should never do anything which might be regarded as malicious or anti-social.\n\nand gives as example:\n\n> Packages should not write in the user’s home filespace (including clipboards), nor anywhere else on the file system apart from the R session’s temporary directory (or during installation in the location pointed to by TMPDIR: and such usage should be cleaned up). Installing into the system’s R installation (e.g., scripts to its bin directory) is not allowed.\n\nPackages can write per default to `tempdir()`, or any other temporary/cache directory, or have no default path at all, as long as the default is not the user's home filespace. \n\n \n\n\n---------------------------------------\n\n# Writing to the `.GlobalEnv`\n\n## Problem\n\nYou are writing per default to the global environment, `.GlobalEnv`, the user's workspace.\n\n## Solution\n\nOmit any default writing to the global environment. \n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nPlease do not modify the global environment (e.g. by using <<-) in your functions. This is not allowed by the CRAN policies.\n\n:::\n\nThe `.GlobalEnv` is the main workspace of users. It can also be accessed by `globalenv()`. Writing to the global environment is forbidden for CRAN packages. \n\nSometimes package maintainers use the operator `<<-`. This operator not only evaluates the expression in the environment it is called in, checks parent environments for an existing definition of the variable. If such a variable is found then its value is redefined, otherwise assignment takes place in the `.GlobalEnv`. \nTo avoid writing to the global environment, the variable must be defined in a parent environment. \n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nfoo <- function(){\n \n # defines the variable in the foo()-function environment\n var <- NULL\n \n foo1 <- function(){\n \n # redefines var but only in the foo() environment as it is the parent of foo1()\n var <<- \"redefined\"\n }\n \n # calls the foo1() function to redefine var\n foo1()\n return(var)\n}\n```\n:::\n\n\n\n\n\nPart of the `.GlobalEnv` is the `.Random.seed` which should not be changed at all. \n\nExcepted from this rule are 'shiny' packages which build interactive web apps. They sometimes need to modify the `.GlobalEnv`.\n\n:::{.callout-note}\n\nCalls of `rm(list = ls())` to remove variables of the current environment, should not be used in examples, vignettes or demos. In functions `rm(list = ls())` can be used, as the active environment is then the function environment instead of the global environment. \n\n:::\n\n\n\n\n---------------------------------------------\n\n\n# Calling `installed.packages()`\n\n## Problem\n\nYou are calling `installed.packages()` to check if a package is installed.\n\n## Solution\n\nInstead of using `installed.packages()`, use `requireNamespace(\"pkg\")` or `require(\"pkg\")` to find out if packages are available.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nYou are using `installed.packages()` in your code. As mentioned in the notes of `installed.packages()` help page, this can be very slow. Therefore do not use `installed.packages()`.\n\n:::\n\n`installed.packages()` outputs a matrix with details of all packages which are installed in the specified libraries. This can be used to check if a specific package is installed. As mentioned in the help file of the [`installed.packages()` function](https://stat.ethz.ch/R-manual/R-devel/library/utils/html/installed.packages.html), it can be very slow under certain circumstances.\n\n> This needs to read several files per installed package, which will be slow on Windows and on some network-mounted file systems. It will be slow when thousands of packages are installed, ...\n\nTherefore, do not use `installed.packages()` in CRAN packages.\n\nThe help file also lists different solutions and the respective, alternative functions.\n\n> ... so do not use it to find out if a named package is installed (use `find.package` or `system.file`) nor to find out if a package is usable (call `requireNamespace` or `require` and check the return value) nor to find details of a small number of packages (use `packageDescription`).\n\nIdeally, use `requireNamespace(\"pkg\")` or `require(\"pkg\")`, both return `FALSE` if a package isn't available, and throw an error conditionally. For more details on package installations in your code see [the corresponding recipe, (yet to come)]().\n\n\n\n--------------\n\n\n# Setting `options(warn = -1)`\n\n## Problem\n\nYou are setting `options(warn = -1)`.\n\n## Solution\n\nConsider using `suppressWarnings()` instead of `options(warn = -1)` if you absolutely need to suppress warnings.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nYou are setting `options(warn=-1)` in your function. This is not allowed. Please rather use `suppressWarnings()` if really needed.\n\n:::\n\nCRAN doesn't allow negative `warn` options. This setting will turn off all warning messages. Even if the settings are correctly restored, as explained in the [Change of Options recipe](#change-of-options-graphical-parameters-and-working-directory), the submission will be rejected.\n\nCRAN recommends using `suppressWarnings()`, which disables warnings only for the specific expression it's applied to, rather than globally.\n\n\n\n", - "supporting": [ - "code_issues_files" - ], + "markdown": "---\ntitle: \"Code Issues\"\nformat: \n html:\n css: style.css\n---\n\n\n\n\n# `T`/`F` Instead of `TRUE`/`FALSE`\n\n## Problem\n\nYou are writing the abbreviated forms of `TRUE` and `FALSE`, `T` and `F` or you are using `T` or `F` as names.\n\n## Solution\n\nChange the abbreviation to the full words or use a different variable name.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nPlease write TRUE and FALSE instead of T and F. Please don't use \"T\" or \"F\" as vector names.\n\n:::\n\nIn 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`.\n\n### Examples\n\nThe first example shows that you cannot overwrite `TRUE`:\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nTRUE <- \"Not TRUE anymore\"\n```\n\n::: {.cell-output .cell-output-error}\n\n```\nError in TRUE <- \"Not TRUE anymore\": invalid (do_set) left-hand side to assignment\n```\n\n\n:::\n\n```{.r .cell-code}\nprint(TRUE)\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] TRUE\n```\n\n\n:::\n:::\n\n\n\n\nThis throws an error as `TRUE` is a reserved word and the value of `TRUE` does not change.\n\n`T` (and `F`) on the other hand can be set to a different value:\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nT <- \"Not TRUE anymore\"\n\nprint(T)\n```\n\n::: {.cell-output .cell-output-stdout}\n\n```\n[1] \"Not TRUE anymore\"\n```\n\n\n:::\n:::\n\n\n\n\nTo avoid any unexpected behaviors and inconsistencies, CRAN reviewers will ask you to write the reserved words, `TRUE` and `FALSE` instead of their abbreviated forms. For the same reason, `T` or `F` should not be used as variable names in your code, examples, tests or vignettes.\n\n--------------------------------------------------------------------\n\n# Setting a Specific Seed\n\n## Problem\n\nIn your functions, you are setting a the random seed to a specific number which cannot be changed.\n\n## Solution\n\nRemove the code that sets the seed. If you want to set it specifically in your functions, users should be able to set no seed if they want. \n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nPlease do not set a seed to a specific number within a function.\n\n:::\n\nChanging 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. \n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nfunction(... , seed = NULL){\n if(!is.null(seed)){\n set.seed(seed)\n }\n \n #the rest of your function can be written here.\n \n}\n```\n:::\n\n\n\nThis allows users to avoid setting a seed if they change the argument to `NULL`. Ideally, the argument is already set to `NULL` per default. \n\n\n\n::: {.callout-note}\n\nIn your examples, vignettes, demos and tests setting a seed is not only allowed but also recommended to ensure reproducible results. \n\n:::\n\n-----------------------------------------------------------\n\n# Using `print()`/`cat()`\n\n## Problem\n\nYou are using functions, like `print()` or `cat()`, to print unsuppressable output to the console.\n\n## Solution\n\nChange `print()`/`cat()` to `message()`, `warning()`, `stop()`, or wrap them in `if(verbose){}`.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nYou write information messages to the console that cannot be easily suppressed.\nIt 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)\n\n:::\n\nInformation 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. \n\n:::{.callout-note}\n\nPrinting in special functions like print, summary, interactive functions or methods for generic functions is accepted. \n\n:::\n\n\nTo allow users to suppress the console output CRAN recommends two different ways: \n\n * exchanging `cat()`/`print()` with other generics\n - [`message()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/message.html): for information messages and status updates \n - [`warning()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/warning.html): for warning, will print a \"Warning: \" before the output\n - [`stop()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/stop.html): for error messages, will print an \"Error: \" before the output and halt the execution\n \nThis allows to use functions like `suppressMessages()` to avoid unwanted output. \n\n * using an additional function argument\n - create one argument in your function to turn off the console output\n - CRAN suggests using `verbose`, other names are accepted\n \nThis example code shows the use of a `verbose` argument to allow users to suppress printing\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nfoo <- function(..., verbose = TRUE){\n # your code\n if(verbose){\n print(\"Whatever you want to say!\")\n }\n # your code\n}\n```\n:::\n\n\n\n\nFunctions can print per default, like the example above, as long as the printing can be turned off (here, by setting `verbose = FALSE`).\n\n:::{.callout-note}\n\n`print()` and `cat()` are not the only functions which can write output onto the console. The issue described in the recipe, also applies to the use of other printing function like `writeLines()`. \nIf you are using loggers to document your functions' process, make sure that users can set their log level such that not messages are displayed.\n\n:::\n\n\n\n---------------------------------------------------------\n\n# Change of Options, Graphical Parameters and Working Directory\n\n## Problem\n\nYou are changing the `par()`, `options()` or `setwd()` in your functions, examples, demos or vignettes without resetting them.\n\n## Solution \n\nReset the changed options, in your functions by using [`on.exit()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/on.exit.html) or in examples, demos and vignettes with an additional line of code after the example.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\nPlease 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. \ne.g.: \n... \noldpar <- par(no.readonly = TRUE) # code line i \non.exit(par(oldpar)) # code line i + 1 \n... \npar(mfrow=c(2,2)) # somewhere after \n... \ne.g.: \nIf 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. \n\nPlease always make sure to reset to user's options(), working directory or par() after you changed it in examples and vignettes and demos. \ne.g.: \noldpar <- par(mfrow = c(1,2)) \n... \npar(oldpar) \n\n:::\n\nIdeally, 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. \nThe reason for this rule is this line stated in the [CRAN Repository Policy](https://cran.r-project.org/web/packages/policies.html):\n\n> The code and examples provided in a package should never do anything which might be regarded as malicious or anti-social.\n\nResetting options is therefore mainly a Quality-of-Life feature for users of your package.\n\nThere are different ways of resetting for functions, and examples, demos or vignettes which are recommended by CRAN. \n\nChanging `par()`, `options()` or `setwd()` all invisibly return the previous values and therefore these can be stored in variables using the assignment operator `<-` and later be restored by calling the variable name as argument in the respective function. \n\n\n**For functions**:\n\nWhen changing options inside one of your package functions, you can use [`on.exit()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/on.exit.html) for restoring. \n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nfoo <- function(x){\n \n # par():\n oldpar <- par(mfrow = c(2,2))\n on.exit(par(oldpar))\n \n # options():\n oldop <- options(digits = 3)\n on.exit(options(oldop))\n \n # setwd():\n oldwd <- setwd(\".\")\n on.exit(setwd(oldwd))\n \n # your code which requires a changed option\n \n}\n```\n:::\n\n\n\n\nThis will reset the `par()`, `options()` and `setwd()`. The use of [`on.exit()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/on.exit.html) 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. \nFor more information, call [`?on.exit()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/on.exit.html) in your console. \n\n\n**For demos, examples and vignettes**:\nSince no function is exited when changing options in examples, [`on.exit()`](https://stat.ethz.ch/R-manual/R-devel/library/base/html/on.exit.html) cannot be used. CRAN recommends the following way for restoring options:\n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\noldpar <- par(mfrow = c(2,2))\n\n# your code which requires a changed option\n\npar(oldpar)\n```\n:::\n\n\n\n\nHere the code will only reset the options if the example runs without breaking. Therefore, try to keep the code between setting and resetting as concise as possible. Restoring the `options()` and `setwd()` can be done using the same principle as for `par()` shown above. \n\n:::{.callout-tip}\n\nIf you need to change more than one option in the same function, example, vignette or demo, you can use `oldpar <- par(no.readonly = TRUE)` or `oldop <- options()` to reset all parameters at once. Saving the entire \nNote, that for `par()` the `no.readonly` argument must be set to `TRUE` or else warnings will be produced.\n\n:::\n\n:::{.callout-note}\n\nThe issue described in the recipe, also applies to the use of other function which change some parameters persistently, like `Sys.setLanguage`. \n\n:::\n\n--------------------------\n\n# Writing Files and Directories to the Home Filespace\n\n## Problem\n\nYou are writing, either by default or within your examples, vignettes, or tests, to the user's home filespace, including the package directory and the current working directory (`getwd()`).\n\n\n## Solution \n\nOmit any default path in your functions and write to `tempdir()` in examples, vignettes or tests. \n\n\n### Details\n\n \n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nPlease ensure that your functions do not write by default or in your examples/vignettes/tests in the user's home filespace (including the package directory and getwd()). This is not allowed by CRAN policies. Please omit any default path in writing functions. In your examples/vignettes/tests you can write to tempdir().\n\n:::\n\nThe [CRAN Repository Policy](https://cran.r-project.org/web/packages/policies.html) states that:\n\n> The code and examples provided in a package should never do anything which might be regarded as malicious or anti-social.\n\nand gives as example:\n\n> Packages should not write in the user’s home filespace (including clipboards), nor anywhere else on the file system apart from the R session’s temporary directory (or during installation in the location pointed to by TMPDIR: and such usage should be cleaned up). Installing into the system’s R installation (e.g., scripts to its bin directory) is not allowed.\n\nPackages can write per default to `tempdir()`, or any other temporary/cache directory, or have no default path at all, as long as the default is not the user's home filespace. \n\n \n\n\n---------------------------------------\n\n# Writing to the `.GlobalEnv`\n\n## Problem\n\nYou are writing per default to the global environment, `.GlobalEnv`, the user's workspace.\n\n## Solution\n\nOmit any default writing to the global environment. \n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nPlease do not modify the global environment (e.g. by using <<-) in your functions. This is not allowed by the CRAN policies.\n\n:::\n\nThe `.GlobalEnv` is the main workspace of users. It can also be accessed by `globalenv()`. Writing to the global environment is forbidden for CRAN packages. \n\nSometimes package maintainers use the operator `<<-`. This operator not only evaluates the expression in the environment it is called in, checks parent environments for an existing definition of the variable. If such a variable is found then its value is redefined, otherwise assignment takes place in the `.GlobalEnv`. \nTo avoid writing to the global environment, the variable must be defined in a parent environment. \n\n\n\n\n::: {.cell}\n\n```{.r .cell-code}\nfoo <- function(){\n \n # defines the variable in the foo()-function environment\n var <- NULL\n \n foo1 <- function(){\n \n # redefines var but only in the foo() environment as it is the parent of foo1()\n var <<- \"redefined\"\n }\n \n # calls the foo1() function to redefine var\n foo1()\n return(var)\n}\n```\n:::\n\n\n\n\n\nPart of the `.GlobalEnv` is the `.Random.seed` which should not be changed at all. \n\nExcepted from this rule are 'shiny' packages which build interactive web apps. They sometimes need to modify the `.GlobalEnv`.\n\n:::{.callout-note}\n\nCalls of `rm(list = ls())` to remove variables of the current environment, should not be used in examples, vignettes or demos. In functions `rm(list = ls())` can be used, as the active environment is then the function environment instead of the global environment. \n\n:::\n\n\n\n\n------------------------------------------------------------------------\n\n# Calling `installed.packages()`\n\n## Problem\n\nYou are calling `installed.packages()` to check if a package is installed.\n\n## Solution\n\nInstead of using `installed.packages()`, use `requireNamespace(\"pkg\")` or `require(\"pkg\")` to find out if packages are available.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=\"false\" collapse=\"true\"}\nYou are using `installed.packages()` in your code. As mentioned in the notes of `installed.packages()` help page, this can be very slow. Therefore do not use `installed.packages()`.\n:::\n\n`installed.packages()` outputs a matrix with details of all packages which are installed in the specified libraries. This can be used to check if a specific package is installed. As mentioned in the help file of the [`installed.packages()` function](https://stat.ethz.ch/R-manual/R-devel/library/utils/html/installed.packages.html), it can be very slow under certain circumstances.\n\n> This needs to read several files per installed package, which will be slow on Windows and on some network-mounted file systems. It will be slow when thousands of packages are installed, ...\n\nTherefore, do not use `installed.packages()` in CRAN packages.\n\nThe help file also lists different solutions and the respective, alternative functions.\n\n> ... so do not use it to find out if a named package is installed (use `find.package` or `system.file`) nor to find out if a package is usable (call `requireNamespace` or `require` and check the return value) nor to find details of a small number of packages (use `packageDescription`).\n\nIdeally, use `requireNamespace(\"pkg\")` or `require(\"pkg\")`, both return `FALSE` if a package isn't available, and throw an error conditionally. For more details on package installations in your code see this [recipe](#installing-software).\n\n------------------------------------------------------------------------\n\n# Setting `options(warn = -1)`\n\n## Problem\n\nYou are setting `options(warn = -1)`.\n\n## Solution\n\nConsider using `suppressWarnings()` instead of `options(warn = -1)` if you absolutely need to suppress warnings.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=\"false\" collapse=\"true\"}\nYou are setting `options(warn=-1)` in your function. This is not allowed. Please rather use `suppressWarnings()` if really needed.\n:::\n\nCRAN doesn't allow negative `warn` options. This setting will turn off all warning messages. Even if the settings are correctly restored, as explained in the [Change of Options recipe](#change-of-options-graphical-parameters-and-working-directory), the submission will be rejected.\n\nCRAN recommends using `suppressWarnings()`, which disables warnings only for the specific expression it's applied to, rather than globally.\n\n------------------------------------------------------------------------\n\n# Installing Software {#installing-software}\n\n## Problem\n\nYou are installing software or packages in your functions, examples, tests or vignettes.\n\n## Solution\n\nCreate special functions for the purpose of installing software and don't install it in examples, tests, or vignettes.\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=\"false\" collapse=\"true\"}\nPlease do not install packages in your functions, examples or vignette. This can make the functions, examples and cran-check very slow.\n:::\n\nPackages should usually not be installed within functions, especially since dependencies should already be listed in the DESCRIPTION. For external software this is typically the same. However, if the purpose of your package is to connect to specific APIs or provides easier installation for some programs, installing software or packages is allowed on CRAN.\n\nTo ensure shorter check times, those functions should not be called within tests, vignettes or examples. The name of function which install software should ideally indicate that, for example:\n\n- `devtools::install_github()`\n\n- `reticulate::install_python()`\n\nThe corresponding help file should also state that software will be installed.\n\n::: callout-note\nEven if it is made clear that installations will happen, the function shouldn't write to the user's home file space, as mentioned in this [recipe](#writing-files-and-directories-to-the-home-filespace).\n:::\n-----------------------------------------\n\n# Using more than 2 Cores\n\n## Problem\n\nYou are using more than 2 CPU cores in your examples, vignettes, tests or during installation. \n\n## Solution\n\nMake sure that you set the maximum number of cores used to 2 in examples, vignettes or tests. \nDuring installation, many modern build systems use the `-j` flag. \n\n\n### Details\n\n::: {.callout-note title=\"CRAN Review Communication\" appearance=\"simple\" icon=false collapse=true}\n\nPlease ensure that you do not use more than 2 cores in your examples, vignettes, etc.\n\n:::\n\n\nCRAN checks run on big, multi-core computers, running many `R CMD check` processes in parallel. Every process is allowed to use a maximum of 2 CPU cores to exercise parallel code in examples and unit tests. When using more than 2 cores, your package will get a NOTE from CRAN checks, saying that it took more CPU time than elapsed time.\n\n::: {.callout-note title=\"CRAN NOTE\" icon=false}\n\nCheck: whether package can be installed, Result: NOTE\\\n  Installation took CPU time 6.9 times elapsed time\\\n\\\nCheck: examples, Result: NOTE\\\n  Examples with CPU time > 2.5 times elapsed time\n \n:::\n\nAutomatic tests will generate a NOTE if more than 2 cores are used in examples, vignettes, tests, or during installation. It’s best to provide an option for setting the number of cores in any function, with the default ideally set to fewer than 2 cores.\n\nSomething that ran as part of the installation process might have started more than two child processes (or threads) at the same time. The solution for this is specific to the build system your package is using. Many modern build systems however, can use the `-j` flag which originated from `GNU Make` (for more information, see their [manual](https://devdocs.io/gnu_make/options-summary#-j%20[jobs]){target=\"_blank\"}).\n\n\n\n", + "supporting": [], "filters": [ "rmarkdown/pagebreak.lua" ], diff --git a/code_issues.qmd b/code_issues.qmd index 57ac3e7..dec111e 100644 --- a/code_issues.qmd +++ b/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): From 8a2981be3f29213c0720492bf9e4494200d3d3b3 Mon Sep 17 00:00:00 2001 From: Baltmann01 Date: Fri, 8 Nov 2024 18:27:35 +0100 Subject: [PATCH 5/5] Update general_issues.qmd --- general_issues.qmd | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/general_issues.qmd b/general_issues.qmd index aa1a8f1..30081bd 100644 --- a/general_issues.qmd +++ b/general_issues.qmd @@ -19,6 +19,12 @@ Where do they end up and who will look at them etc... --> The description field in the DESCRIPTION file should be a short paragraph (2+ sentences) on the package's purpose, motivation and may include further references to the package documentation website. You can also consider the Description length to be similar to a blurb or synopsis written on the inside jacket of a book - brief but informative. A good example of this description length is included in the ['tidyverse'](https://github.com/tidyverse/tidyverse/blob/main/DESCRIPTION#L8-L12) package. +::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true} + +The Description field is intended to be a (one paragraph) description of what the package does and why it may be useful. Please add more details about the package functionality and implemented methods in your Description text. + +::: + # Structuring of Examples As part their documentation most functions have example code in their .Rd-files marked by the `\examples{}` tag. @@ -29,7 +35,7 @@ Examples serve two major purposes for packages on CRAN. For several reasons, some examples cannot be run as tests. Therefore, CRAN has several wrappers to structure them. The following list gives a short overview of the most common ones and when to use them. -* **Unwrapper:** +* **Unwrapped:** + Short examples to show the functionality of the code + CRAN recommends the use of toy examples on small data sets + Ideally, also cover some edge cases @@ -69,6 +75,19 @@ All wrappers must still be placed inside the `\examples{}` tag. ::: +::: {.callout-note title="Examples of CRAN Review Communication" appearance="simple" icon=false collapse=true} + +\\dontrun\{\} should only be used if the example really cannot be executed (e.g. because of missing additional software, missing API keys, ...) by the user. That's why wrapping examples in \\dontrun\{\} adds the comment ("# Not run:") as a warning for the user. Does not seem necessary. Please replace \\dontrun with \\donttest. + +Please unwrap the examples if they are executable in < 5 sec, or replace \\dontrun\{\} with \\donttest\{\}. + +Functions which are supposed to only run interactively (e.g. shiny) should be wrapped in if(interactive()). Please replace \\dontrun\{\} with if(interactive())\{\} if possible, then users can see that the functions are not intended for use in scripts. + +All your examples are wrapped in \\donttest\{\} and therefore do not get tested. +Please unwrap the examples if that is feasible and if they can be executed in < 5 sec for each Rd file or create additionally small toy examples to allow automatic testing. + +::: + # Package Size Ideally, CRAN packages should be under 5 Mb. There are *very few exceptions* mostly for a larger `inst/` folder (and these will trigger flags for every future submission). They must be approved by a CRAN team member and since every accepted version is saved on CRAN, they are very hesitant. @@ -83,3 +102,9 @@ If your package exceeds the recommended 5 Mb limit, it will generate a NOTE in t ::: +::: {.callout-note title="CRAN Review Communication" appearance="simple" icon=false collapse=true} + +A CRAN package should not be larger than 5 MB. Please reduce the size. + +::: +