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)
[![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, coerce, modify, and validate
`CITATION.cff` files automatically for **R** packages, along with tools and
examples for working with .cff files 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 gaining popularity 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
fully supported this citation format [@druskat_stephan_making_2021]. GitHub
support is of special interest:

<figure>

![](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] allow for generating `codemeta.json` files from R
package metadata.

## The cffr package

**cffr** maximizes data extraction by utilizing both the `DESCRIPTION` file and
the `CITATION` file (if present) from your package. Note that **cffr** works
best if your package passes `R CMD check/devtools::check()`.

```{r}
#| label: 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) {
    TRUE
  },
  error = function(e) {
    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

Most commonly, from within your package folder, you'll simply run `cff_write()`,
which 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
#>
#> 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("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)
```

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 to keep your `CITATION.cff` file up-to-date is using GitHub
Actions. Use `cff_gha_update()` function to install a GitHub Action that will
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 ./.github/workflows/update-citation-cff.yaml
#> ℹ 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 [![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'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 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.

## Code of Conduct

Please note that 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), 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