README.qmd

---
format: gfm
bibliography: inst/REFERENCES.bib
link-citations: true
default-image-extension: ''
knitr:
  opts_chunk:
    collapse: true
    comment: "#>"
    fig.path: "man/figures/README-"
    tidy: "styler"
    dev: "ragg_png"
    warning: false
    message: false
    out.width: "100%"
---

<!-- README.md is generated from README.qmd. Please edit that file -->

# cffr <a href="https://docs.ropensci.org/cffr/"><img src="man/figures/logo.png" alt="cffr website" align="right" height="139"/></a>

<!-- badges: start -->

[![CRAN-status](https://www.r-pkg.org/badges/version/cffr)](https://CRAN.R-project.org/package=cffr)
[![CRAN-results](https://badges.cranchecks.info/worst/cffr.svg)](https://cran.r-project.org/web/checks/check_results_cffr.html)
[![Downloads](https://cranlogs.r-pkg.org/badges/grand-total/cffr?color=blue)](https://cran.r-project.org/package=cffr)
[![R-CMD-check](https://github.com/ropensci/cffr/actions/workflows/check-full.yaml/badge.svg)](https://github.com/ropensci/cffr/actions/workflows/check-full.yaml)
[![codecov](https://codecov.io/gh/ropensci/cffr/branch/main/graph/badge.svg?token=YRO3XL8RWK)](https://app.codecov.io/gh/ropensci/cffr)
[![Coverage
Status](https://coveralls.io/repos/github/ropensci/cffr/badge.svg?branch=main)](https://coveralls.io/github/ropensci/cffr?branch=main)
[![r-universe](https://ropensci.r-universe.dev/badges/cffr)](https://ropensci.r-universe.dev/cffr)
[![CITATION-cff](https://github.com/ropensci/cffr/actions/workflows/cff-validator.yaml/badge.svg)](https://github.com/ropensci/cffr/actions/workflows/cff-validator.yaml)
[![DOI](https://joss.theoj.org/papers/10.21105/joss.03900/status.svg)](https://doi.org/10.21105/joss.03900)
[![Project Status: Active - The project has reached a stable, usable state and
is being actively
developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
![GitHub code size in
bytes](https://img.shields.io/github/languages/code-size/ropensci/cffr)
[![peer-review](https://badges.ropensci.org/463_status.svg)](https://github.com/ropensci/software-review/issues/463)

<!-- badges: end -->

**cffr** provides utilities to generate, read, write, modify and validate
Citation File Format metadata for **R** packages. It also includes tools and
examples for working with `*.cff` files more generally.

## What is a `CITATION.cff` file?

A `CITATION.cff` file follows the [Citation File Format
(CFF)](https://citation-file-format.github.io/) [@druskat_citation_2021]
(v1.2.0). It contains human- and machine-readable citation metadata for software
and datasets. Developers can include it in a repository to explain how to cite
their software.

This format is increasingly used in the software citation ecosystem.
[**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-) support
this citation format [@druskat_stephan_making_2021]. **GitHub** support is of
special interest:

<figure>

![GitHub citation support announcement](vignettes/tweet-1.png){.mx-auto .d-block
fig-align="center" width="400"}

```{=html}
<figcaption class="blockquote-footer">Nat Friedman (@natfriedman) July 27, 2021</figcaption>
</figure>
```

See [Enhanced support for citations on
**GitHub**](https://github.blog/news-insights/company-news/enhanced-support-citations-github/)
[@smith2021] for more information.

### 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 by The CodeMeta
Project) is to provide citation metadata such as title, authors, publication
year and venue [@fenner2021]. The packages **codemeta** [@codemeta] and
**codemetar** [@codemetar2021] can generate `codemeta.json` files from **R**
package metadata.

## The **cffr** package

**cffr** uses metadata from both your package's `DESCRIPTION` file and its
`CITATION` file, if present. **cffr** works best if your package passes
`R CMD check` or `devtools::check()`.

```{r}
#| label: count_cffr
#| echo: false
#| results: asis
cat("\n")
today <- Sys.Date()
# Try to count GitHub repositories 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 the repository count.
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),
    mode = "wb"
  ),
  warning = function(e) {
    TRUE
  },
  error = function(e) {
    TRUE
  }
)
# If the request is 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 of ",
    today,
    " there are at least ",
    nreps,
    " repositories on GitHub using **cffr**. ",
    "[Browse the search results]",
    "(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 development version of **cffr** with:

```{r}
#| eval: false
pak::pak("ropensci/cffr")
```

Alternatively, you can install **cffr** from
[**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

Most commonly, from within your package directory, you run `cff_write()`. It
creates a `cff` object, writes it to a `CITATION.cff` file and validates it in a
single command:

```{r}
#| eval: false
library(cffr)

# For in-development packages.
cff_write()
#>
#> CITATION.cff generated.
#>
#> ══ Validating CFF ══════════════════════════════════════════════════════════════
#> ✔ CITATION.cff is valid.
```

**cffr** also provides custom print methods and helper functions for customizing
`CITATION.cff` files and integrating them into your workflows.

This basic example shows how to create a `cff` object (see `?cff` for more
information). Here, we create a `cff` object from the metadata of the **knitr**
package:

```{r }
library(cffr)

# Example with an installed package.
test <- cff_create("knitr")
```

<details>

<summary><code>CITATION.cff</code> for <strong>knitr</strong></summary>

```{r}
#| echo: false
#| comment: ''
test
```

</details>

We can validate the result using `cff_validate()`:

```{r }
cff_validate(test)
```

See the [reference
documentation](https://docs.ropensci.org/cffr/reference/index.html) and
`vignette("cffr", package = "cffr")` to learn more about working with `cff`
objects.

### Keep your `CITATION.cff` file up to date

#### **GitHub Actions**

The easiest way to keep your `CITATION.cff` file up to date is to use **GitHub
Actions**. Use `cff_gha_update()` to install a **GitHub Actions** workflow that
updates your `CITATION.cff` file in the following cases:

- When you publish a new release of the package on **GitHub**.
- Each time you modify your `DESCRIPTION` or `inst/CITATION` files.
- When you run the workflow manually.

```{r}
#| eval: false
cff_gha_update()

#> ✔ Installing ./.github/workflows/update-citation-cff.yaml.
#> ℹ Adding .github to .Rbuildignore.
```

See the [example workflow
file](https://github.com/ropensci/cffr/blob/main/.github/workflows/update-citation-cff.yaml).

#### Git pre-commit hook

[![Experimental](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](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 is used to inspect the snapshot that is about to be committed, to see if
> you have 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`.

Install a pre-commit hook with `cff_git_hook_install()`. This function requires
the **usethis** package.

### 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/) [@hernangomez_cffr_2021]
- [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/)
  [@hernangomez_test_2021]

## Related packages

- **citation** [@citation22] includes an `r2cff()` function that creates a
  `CITATION.cff` file using the information in your `DESCRIPTION` file. It also
  provides minimal validity checks.
- **handlr** [@handlr] is a tool for converting among citation formats,
  including `*.cff` files.
- **codemeta** [@codemeta] / **codemetar** [@codemetar2021] provide similar
  tools for creating `codemeta.json` files, another format for storing and
  sharing software metadata.

## Code of conduct

The **cffr** project is released with a [Contributor Code of
Conduct](https://docs.ropensci.org/cffr/CODE_OF_CONDUCT.html). By contributing
to this project, you agree to abide by its terms.

## 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), which is generated from the
information in a `CITATION.cff` file 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 information.

## References