Citing software from CITATION.cff#

A repository that keeps a CITATION.cff file already states how its software should be cited, and GitHub’s “Cite this repository” button reads the same file. A guide for that repository can read the same file with a cff configuration, rather than restating the title, authors, and location in documenteer.toml.

A file that describes the software alone#

Documenteer’s own repository is a basic example. Its CITATION.cff holds one record, which describes the package, and no preferred-citation:

CITATION.cff#
cff-version: 1.2.0
message: If you use Documenteer, please cite it using the metadata from this file.
type: software
title: Documenteer
authors:
  - family-names: Sick
    given-names: Jonathan
    orcid: https://orcid.org/0000-0003-3001-676X
    affiliation: Vera C. Rubin Observatory
repository-code: https://github.com/lsst-sqre/documenteer
url: https://documenteer.lsst.io
license: MIT

This site’s entry for it names the file, a label, and a note, and marks the citation preferred:

docs/documenteer.toml#
[[project.citations]]
cff = "../CITATION.cff"
label = "Software"
preferred = true
note = "Cite the version of Documenteer you used; this site documents the version shown."

The path is resolved relative to documenteer.toml, so a file at the repository root is ../CITATION.cff from a docs/ directory.

The entry is preferred rather than self because the software has no DOI. self claims that this site is a DOI’s registered landing page, so it requires a DOI, while preferred only says which citation the site asks readers to use (see Software that has never been deposited). The card below is rendered from that entry:

Software

Sick, Jonathan. Documenteer (version 2.5.0b6.dev7+g51839207b). https://documenteer.lsst.io

BibTeX
@software{documenteer,
    author = {Sick, Jonathan},
    title = {{Documenteer}},
    version = {2.5.0b6.dev7+g51839207b},
    url = {https://documenteer.lsst.io}
}

Cite the version of Documenteer you used; this site documents the version shown.

Three things about that card come from reading the file’s top-level record:

  • The location is the file’s url, this site, rather than its repository-code. A file that names a landing page is cited at that page, and at the repository only when the file names no landing page.

  • The version is the one this build of the documentation was made from, although neither the file nor the entry states one. An entry reading a repository’s own record describes this site’s own package, so it takes the file’s version when the file states one and the site’s own project.version otherwise.

  • The missing date isn’t reported. Software located by where it lives, rather than by a DOI, has no publication event to date, so an entry reading a file’s top-level record is exempt from the undated-citation warning.

The entry states no type either, and doesn’t need to. A top-level record that declares none is read as software, the default that CFF defines for that key, so the citation composes as @software in BibTeX and is described as a SoftwareSourceCode in the site’s metadata.

A file that prefers a paper#

Many repositories ask to be cited by a paper that describes them, and say so with a preferred-citation record in the same file. That paper’s landing page belongs to its publisher, so the site marks it preferred and marks nothing self:

documenteer.toml#
[[project.citations]]
cff = "../CITATION.cff"
label = "Paper"
preferred = true
note = "Cite this paper in publications that use the package."

An entry reads the file’s preferred-citation by default, as GitHub’s button does, and falls back to the top-level record when the file has none. That fallback is how the Documenteer entry above got its software record without asking for it. The site then displays that citation as its preferred citation, while no page of the site claims to be the paper’s landing page. Setting self on that entry instead is an error that the build reports, because it would present every page of the site as the paper’s full text, a claim only the paper’s publisher can make.

Such a repository is often worth citing twice: the paper for the work, and the package for the code that was run. A second entry against the same file, with cff_preferred = false, reads the file’s top-level record rather than its preferred citation:

documenteer.toml#
[[project.citations]]
cff = "../CITATION.cff"
cff_preferred = false
label = "Software"
in_footer = true
note = "Cite the version you ran; this page names the version it documents."

The package is cited by where it lives: the file’s url, or its repository-code when it names no landing page. Setting in_footer = true puts it in the footer beside the preferred paper, so readers see both.

Versions and dates#

The software entry states no version but gets one anyway, because an entry reading a repository’s own record describes this site’s own package. Against a CITATION.cff for safir, released in 2020 and documented at 12.3.0, the entry renders:

SOFTWARE

NSF-DOE Vera C. Rubin Observatory (2020). Safir (version 12.3.0).
https://github.com/lsst-sqre/safir

Cite the version you ran; this page names the version it documents.

The version is what a software citation needs to convey, which is why the note is written around it rather than around the year. Continuously released software has no single publication date. Its date is conventionally the year of its first release. That convention is stable (every later release is cited the same way, so a reader’s bibliography doesn’t churn), but the year doesn’t identify the code that ran. The version does. That’s also why an entry like this one, software located by its repository and stating no date, isn’t reported as undated. A preferred-citation record is different: it names a work other than the repository, and an undated one is reported like any other work.

A file’s date-released dates the top-level record, and a preferred-citation carries its own year or date-published. An entry that reads one record never takes the other’s date. For a dated software citation, write the date in the record the entry reads, or on the entry itself with date, which takes precedence over the file.

Further reading#

To learn more about the CITATION.cff standard and related tooling, see the Citation File Format website.