Module software 

Software citations (#614, ADR-0058): a GitHub release or tag cited as @software, and which Zenodo DOI a software record is cited by.

Papers cite their code, often as a GitHub release with no DOI (https://github.com/srwhite59/HFDMRG.jl/releases/tag/v0.1.0). cite took DOIs and arXiv ids only, so those entries were written by hand.

What is read, and from where – only when the caller names a GitHub URL:

• api.github.com GET /repos/{owner}/{repo} for the repository, then /releases/tags/{tag} (or /releases/latest for a bare repository URL). A tag with no release falls back to the tag’s commit date (/commits/{tag}).
• raw.githubusercontent.com /{owner}/{repo}/{tag or HEAD}/CITATION.cff, the authors’ own statement of how to cite them. Its authors and title win over the repository’s owner and name.

CITATION.cff is YAML. Only its top-level scalars and the top-level authors list are read (parse_cff), by a line reader rather than a YAML crate: those are the fields a citation needs, CFF writers emit them in plain block style, and anything the reader cannot follow is skipped, never guessed – an unreadable file cites as if it were absent.

Structs

Cff

What CITATION.cff says, as far as a citation needs it.

GithubRef

A GitHub repository, optionally at a tag. The fields are private: only GithubRef::parse makes one from outside this module, so the owner, repository and tag always passed its checks before they are joined onto an API path (#649 review).

SoftwareCitation

A software citation resolved from GitHub.

Enums

ZenodoDoi

Which DOI a Zenodo software record is cited by (#614).

Constants

GITHUB_API

HTTP source key for the GitHub REST API.

GITHUB_API_BASE_ENV

Base-URL override for GITHUB_API.

GITHUB_RAW

HTTP source key for raw.githubusercontent.com.

GITHUB_RAW_BASE_ENV

Base-URL override for GITHUB_RAW.

Functions

explain

What a GitHub error means, when the status alone would mislead: a 403 is either the spent unauthenticated limit or a repository that is not public, and GitHub’s status does not say which.

github_resolves

Whether g still resolves: the repository, and the release or tag the URL names. Ok(false) for a 404 at either; transport failures are errors.

parse_cff

Read the citation fields of a CITATION.cff: top-level title, version, doi, date-released, and the top-level authors list. Nested blocks (preferred-citation, identifiers, references) are skipped, so their own authors and title are never mistaken for the software’s.

resolve_github

Resolve g against GitHub: repository, release (or the tag’s commit), and CITATION.cff.

zenodo_doi

Classify a DataCite record’s DOI by its relatedIdentifiers: a version DOI points IsVersionOf at its concept; a concept DOI HasVersions. None when the record says neither (not Zenodo-style versioning).