-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.Rmd
299 lines (234 loc) · 10.5 KB
/
README.Rmd
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
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
---
output: github_document
bibliography: inst/REFERENCES.bib
link-citations: yes
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# cffr <a href="https://docs.ropensci.org/cffr/"><img src="man/figures/logo.png" alt="cffr website" align="right" height="139"/></a>
<!-- badges: start -->
[](https://CRAN.R-project.org/package=cffr)
[](https://cran.r-project.org/web/checks/check_results_cffr.html)
[](https://cran.r-project.org/package=cffr)
[](https://github.com/ropensci/cffr/actions/workflows/check-full.yaml)
[](https://github.com/ropensci/cffr/actions/workflows/rhub.yaml)
[](https://app.codecov.io/gh/ropensci/cffr)
[](https://ropensci.r-universe.dev/cffr)
[](https://github.com/ropensci/cffr/actions/workflows/cff-validator.yml)
[](https://doi.org/10.21105/joss.03900)
[](https://www.repostatus.org/#active)
[](https://github.com/ropensci/software-review/issues/463)
<!-- badges: end -->
**cffr** provides utilities to generate, coerce, modify and validate
`CITATION.cff` files automatically for **R** packages, as well as tools and
examples for working with .cff more generally.
## What is a `CITATION.cff` file?
[Citation File Format (CFF](https://citation-file-format.github.io/))
[@druskat_citation_2021] (v1.2.0) are plain text files with human- and
machine-readable citation information for software (and datasets). Code
developers can include them in their repositories to let others know how to
correctly cite their software.
This format is becoming popular within the software citation ecosystem. Recently
[GitHub](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files),
[Zenodo](https://citation-file-format.github.io/#/supported-by-zenodo-) and
[Zotero](https://citation-file-format.github.io/#/supported-by-zotero-) have
included full support of this citation format [@druskat_stephan_making_2021].
GitHub support is of special interest:
```{r echo=FALSE, out.width="400", fig.align='center', fig.alt="Tweet of Nat Friedman about CFF files"}
knitr::include_graphics("vignettes/tweet-1.png")
```
*--- Nat Friedman (\@natfriedman) July 27, 2021*
See [Enhanced support for citations on
GitHub](https://github.blog/news-insights/company-news/enhanced-support-citations-github/)
[@smith2021] for more info.
### Related projects
[The CodeMeta Project](https://codemeta.github.io/) [@jones2017] creates a
concept vocabulary that can be used to standardize the exchange of software
metadata across repositories and organizations. One of the many uses of a
`codemeta.json` file (created following the standards defined on The CodeMeta
Project) is to provide citation metadata such as title, authors, publication
year, and venue [@fenner2021]. The packages **codemeta** [@codemeta] /
**codemetar** [@codemetar2021] allows to generate `codemeta.json` files from R
packages metadata.
## The cffr package
**cffr** maximizes the data extraction by using both the `DESCRIPTION` file and
the `CITATION` file (if present) of your package. Note that **cffr** works best
if your package pass `R CMD check/devtools::check()`.
```{r count_cffr, echo=FALSE, results='asis'}
cat("\n")
today <- Sys.Date()
# Try get the count of GitHub repos here
token <- (Sys.getenv(c("GITHUB_PAT", "GITHUB_TOKEN")))
token <- token[!token %in% c(NA, NULL, "")][1]
ghtoken <- paste("token", token)
tmpfile <- tempfile(fileext = ".json")
# Get numbers of repos
api_url <- paste0(
"https://api.github.com/search/code?q=cffr+extension:",
"cff+filename:CITATION"
)
res <- tryCatch(
download.file(api_url,
tmpfile,
quiet = TRUE,
headers = c(Authorization = ghtoken)
),
warning = function(e) {
return(TRUE)
},
error = function(e) {
return(TRUE)
}
)
# If not successful
if (isTRUE(res)) {
cat(paste0(
"\n", "See [some projects already using **cffr**]",
"(https://github.com/search?q=cffr%20path%3A**%2FCITATION.cff&type=code)",
"."
))
} else {
nreps <- as.integer(jsonlite::read_json(tmpfile)$total_count)
cat(paste0(
"As per ", today, " there are at least ", nreps,
" repos on GitHub using **cffr**. ", "[Check them out here]",
"(https://github.com/search?q=cffr%20path%3A**%2FCITATION.",
"cff&type=code)."
))
}
cat("\n")
```
### Installation
Install **cffr** from [CRAN](https://CRAN.R-project.org/package=cffr):
```{r, eval=FALSE}
install.packages("cffr")
```
You can install the developing version of **cffr** with:
```{r, eval=FALSE}
remotes::install_github("ropensci/cffr")
```
Alternatively, you can install **cffr** using the
[r-universe](https://ropensci.r-universe.dev/cffr):
```{r, eval=FALSE}
# Install cffr in R:
install.packages("cffr",
repos = c("https://ropensci.r-universe.dev", "https://cloud.r-project.org")
)
```
### Example
By default most often from within your package folder you'll simply run
`cff_write()`, that creates a `cff` object, write it on a `CITATION.cff` file
and validates it on a single command:
```{r, eval=FALSE}
library(cffr)
# For in-development packages
cff_write()
#>
#> CITATION.cff generated
#>
#> cff_validate results-----
#> Congratulations! This .cff file is valid
```
However, **cffr** provides also custom print methods and mechanisms that allows
you to customize the `CITATION.cff` and integrate them in your workflows.
This is a basic example which shows you how to create a `cff` object (see `?cff`
for more info). In this case, we are creating a `cff` object from the metadata
of the **rmarkdown** package:
```{r }
library(cffr)
# Example with an installed package
test <- cff_create("rmarkdown")
```
<details>
<summary><code>CITATION.cff</code> for <strong>rmarkdown</strong></summary>
```{r, echo=FALSE, comment=""}
test
```
</details>
<p>
We can validate the result using `cff_validate()`:
```{r }
cff_validate(test)
```
Check the [docs](https://docs.ropensci.org/cffr//reference/index.html) and
`vignette("cffr", package = "cffr")` to learn how to work with `cff` objects.
### Keep your `CITATION.cff` file up-to-date
#### GitHub Actions
The easiest way for keeping you `CITATION.cff` file up-to-date is using GitHub
Actions. Use `cff_gha_update()`function to install a GitHub Action that would
update your `CITATION.cff` file on the following events:
- When you publish a new release of the package on your GitHub repo.
- Each time that you modify your DESCRIPTION or inst/CITATION files.
- The action can be run also manually.
```{r, eval=FALSE}
cff_gha_update()
#> Installing update-citation-cff.yaml on './.github/workflows'
#> Adding .github to .Rbuildignore
```
See the example workflow file
[here](https://github.com/ropensci/cffr/blob/main/.github/workflows/update-citation-cff.yaml).
#### Git pre-commit hook [](https://lifecycle.r-lib.org/articles/stages.html#experimental)
You can also use a [git pre-commit
hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_committing_workflow_hooks):
> The `pre-commit` hook is run first, before you even type in a commit message.
> It's used to inspect the snapshot that's about to be committed, to see if
> you've forgotten something, to make sure tests run, or to examine whatever you
> need to inspect in the code. Exiting non-zero from this hook aborts the
> commit, although you can bypass it with `git commit --no-verify`.
A specific pre-commit hook can be installed with `cff_git_hook_install()`. If
you want to use a pre-commit hook, please make sure you have the **testthat**
package installed.
### Learn more
Check the following articles to learn more about **cffr**:
- [cffr: Create a CITATION.cff File for your R
Package](https://ropensci.org/blog/2021/11/23/cffr/)
- [How I Test cffr on (about) 2,000 Packages using GitHub Actions and
R-universe](https://ropensci.org/blog/2021/11/23/how-i-test-cffr/)
## Related packages
- **citation** [@citation22] includes a function `r2cff` that creates a
`CITATION.cff` file (v1.1.0) using the information of your `DESCRIPTION`
file. It also provide minimal validity checks.
- **handlr** [@handlr]: Tool for converting among citation formats, including
`*.cff` files.
- **codemeta** [@codemeta] / **codemetar** [@codemetar2021] provides similar
solutions for creating `codemeta.json` file, another format for storing and
sharing software metadata.
## Citation
Hernangómez, D., (2021). cffr: Generate Citation File Format Metadata for R
Packages. Journal of Open Source Software, 6(67), 3900,
<https://doi.org/10.21105/joss.03900>
A BibTeX entry for LaTeX users is:
``` bibtex
@article{hernangomez2021,
title = {{cffr}: Generate Citation File Format Metadata for {R} Packages},
author = {Diego Hernangómez},
year = 2021,
journal = {Journal of Open Source Software},
publisher = {The Open Journal},
volume = 6,
number = 67,
pages = 3900,
doi = {10.21105/joss.03900},
url = {https://doi.org/10.21105/joss.03900}
}
```
You can also use the [citation provided by
GitHub](https://github.com/ropensci/cffr), that is generated from the
information of a `CITATION.cff` created with **cffr**. See [About CITATION
files](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files)
for more info.
## References
::: {#refs}
:::
[](https://ropensci.org)