-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathdescription_issues.qmd
233 lines (133 loc) · 9.23 KB
/
description_issues.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
---
title: "DESCRIPTION File Issues"
subtitle: "The DESCRIPTION Files Issues chapter features recipes on content formatting, license structuring, and how to include additional background context & links."
format:
html:
css: style.css
---
# Formatting Software Names
## Problem
The automatic spell check has flagged a software name as incorrect and results in a NOTE.
## Solution
All 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.
### 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:
```
Description: The goal of 'readr' is to provide a fast and friendly way to
read rectangular data (like 'csv', 'tsv', and 'fwf'). It is designed
to flexibly parse many types of data found in the wild, while still
cleanly failing when data unexpectedly changes.
```
------------------------------------------------------------------------
# Explaining Acronyms
## Problem
You are using acronyms in your DESCRIPTION file or they are flagged by the automatic spell check.
## Solution
Document 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.
### 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.
------------------------------------------------------------------------
# LICENSE files
## Problem
Some 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/).
## Solution
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
path_licenses <- list.files(path = R.home(), "license.db", full.names = TRUE, recursive = TRUE)
licenses_doc <- as.data.frame(read.dcf(path_licenses))
```
If 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.
::: callout-tip
## Tip
Licenses should be FOSS, or allowed by [R](https://svn.r-project.org/R/trunk/share/licenses/license.db).
:::
------------------------------------------------------------------------
# Title Case
## Problem
The 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.
## Solution
The package Title field in the DESCRIPTION file must be in Title Case, except words like "a", "the" or "of".
### 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}
tools::toTitleCase("web application framework for R")
```
::: callout-note
There 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.).
It 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.
:::
------------------------------------------------------------------------
# Using Authors@R
## Problem
You have not properly declared the authors, maintainers and copyright holders in the `Authors@R` section of the DESCRIPTION file.
## Solution
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 = "[email protected]"),
    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}
Authors@R: person("Jane", "Smith", email = "[email protected]",
role = c("aut", "cre"), ORCID = "<USER-ORCID>")
```
::: callout-note
The Maintainer and Author fields are automatically generated, so you don't need to add them manually.
If 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.
:::
------------------------------------------------------------------------
# References
## Problem
The reference link in the Description field is incorrectly formatted or isn't clickable.
## Solution
Remove the space after <doi:...> or <https:...> to enable the reference link.
Write the reference in the form: Authors (year) <doi:...>.
### 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) <doi:...>
authors (year, ISBN:...)
or if those are not available: <https:...>
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 ['GA'](https://cran.r-project.org/web/packages/GA/index.html) package:
```
Description: Flexible general-purpose toolbox implementing genetic algorithms (GAs) for stochastic optimisation. Binary, real-valued, and permutation representations are available to optimize a fitness function, i.e. a function provided by users depending on their objective function. Several genetic operators are available and can be combined to explore the best settings for the current task. Furthermore, users can define new genetic operators and easily evaluate their performances. Local search using general-purpose optimisation algorithms can be applied stochastically to exploit interesting regions. GAs can be run sequentially or in parallel, using an explicit master-slave parallelisation or a coarse-grain islands approach. For more details see Scrucca (2013) <doi:10.18637/jss.v053.i04> and Scrucca (2017) <doi:10.32614/RJ-2017-008>.
```
::: callout-tip
Including 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.
:::