README

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) (Druskat et al. 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, Zenodo and Zotero have included full support of this citation format (Druskat 2021). GitHub support is of special interest:

Related projects

The CodeMeta Project (Jones et al. 2017) 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 (Fenner 2021). The packages codemeta (Boettiger and Salmon 2021a) / codemetar (Boettiger and Salmon 2021b) 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().

As per 2024-08-11 there are at least 296 repos on GitHub using cffr. Check them out here.

Installation

# 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:

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:

library(cffr)

# Example with an installed package
test <- cff_create("rmarkdown")

cff_validate(test)
#> ══ Validating cff ══════════════════════════════════════════════════════════════
#> ✔ Congratulations! This <cff> is valid

Check the docs 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:

cff_gha_update()

#> Installing update-citation-cff.yaml on './.github/workflows'
#> Adding .github to .Rbuildignore

Git pre-commit hook

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

Related packages

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

@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}
}

References

Boettiger, Carl, and Maëlle Salmon. 2021a. codemeta: A Smaller codemetar Package. https://CRAN.R-project.org/package=codemeta.

———. 2021b. codemetar: Generate ’CodeMeta’ Metadata for R Packages.

Chamberlain, Scott. 2022. handlr: Convert Among Citation Formats.

Dietrich, Jan Philipp, and Waldir Leoncio. 2022. citation: Software Citation Tools.

Druskat, Stephan. 2021. “Making Software Citation Easi(er) - The Citation File Format and Its Integrations.” https://doi.org/10.5281/zenodo.5529914.

Druskat, Stephan, Jurriaan H. Spaaks, Neil Chue Hong, Robert Haines, James Baker, Spencer Bliven, Egon Willighagen, David Pérez-Suárez, and Alexander Konovalov. 2021. “Citation File Format.” https://doi.org/10.5281/zenodo.5171937.

Fenner, Martin. 2021. “We Need Your Feedback: Aligning the CodeMeta Vocabulary for Scientific Software with Schema.org.” https://doi.org/10.5438/a49j-x692.

Jones, Matthew B, Carl Boettiger, Abby Cabunoc Mayes, Arfon Smith, Peter Slaughter, Kyle Niemeyer, Yolanda Gil, et al. 2017. CodeMeta: An Exchange Schema for Software Metadata. KNB Data Repository. https://doi.org/10.5063/SCHEMA/CODEMETA-2.0.

Smith, Arfon. 2021. “Enhanced Support for Citations on GitHub.” https://github.blog/news-insights/company-news/enhanced-support-citations-github/.

cffr

What is a `CITATION.cff` file?

The cffr package

Installation

Example

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

GitHub Actions

Git pre-commit hook

Learn more

Citation

References

cffr

What is a CITATION.cff file?

Related projects

The cffr package

Installation

Example

Keep your CITATION.cff file up-to-date

GitHub Actions

Git pre-commit hook

Learn more

Related packages

Citation

References

What is a `CITATION.cff` file?

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