Making research software citable and credited
Use this skill when someone wants their research software to be cited,
discovered, and formally recognised: adding a citation file, writing
machine-readable metadata, getting a persistent identifier, or building an
evidence base of who contributed. Software has no title page, so the
information needed to cite it is often hard to find - a citation file and
structured metadata are what let both humans and tools cite the exact work
correctly. Advise concrete files in the repository
root, not abstractions.
Start here: what a citable project needs
For most projects, recommend all four in the repository root:
CITATION.cff - machine-readable citation metadata.codemeta.json - richer discovery/interoperability metadata.- A DOI from an archive like Zenodo, minted per release.
- A
CONTRIBUTORS file - human-readable team record alongside the
machine-readable ones.
A software citation itself should carry: title, the specific version used,
authors/creators, a DOI or other stable link, and the repository URL - the
version matters for reproducibility.
Write a CITATION.cff file
The Citation File Format is a structured plaintext (YAML) format; a valid
CITATION.cff in the repo root is reused automatically by GitHub, Zenodo,
and Zotero. Do not hand-craft the syntax from
memory - point the user at the CFFINIT generator, or start from the official
example and validate with cffconvert.
Checklist of core fields to populate:
cff-version - the CFF schema version (e.g. 1.2.0).message - the "please cite as" instruction.title - the official software name.authors - each with given-names, family-names, and an orcid where
available; an author may instead be a name for an organisation.version - the release being cited.date-released - the release date.doi - the release or concept DOI once minted.repository-code - the source repository URL.license - an SPDX identifier.- If a paper should be cited instead of, or alongside, the software, add a
preferred-citation block pointing to the article and its DOI.
Minimal shape to adapt (validate before committing):
cff-version: 1.2.0
message: "If you use this software, please cite it as below."
title: Your Software Name
version: 1.0.0
date-released: 2026-01-15
doi: 10.5281/zenodo.1234567
repository-code: https://github.com/yourusername/your-repo
license: MIT
authors:
- given-names: First
family-names: Author
orcid: https://orcid.org/0000-0002-1825-0097
affiliation: University of Edinburgh
Tell the user to generate with CFFINIT and validate with cffconvert rather
than trusting a hand-edited file.
Describe the software with CodeMeta
codemeta.json is a JSON-LD metadata standard (extending Schema.org) that
travels between archives and registries - Zenodo, FigShare, InvenioRDM, and
Software Heritage can ingest it, so metadata is not re-entered when getting a
DOI. Recommend it whenever discovery,
interoperability, or DOI minting is in play. Match the type of metadata to
the goal: citation metadata for academic credit, versions and dependencies
for reproducing an analysis, keywords and descriptions for discoverability.
Field checklist for a complete record:
name, description, version - identity and release.author and contributor - each a Person with givenName,
familyName, and an ORCID as identifier.license - an SPDX URL (e.g. https://spdx.org/licenses/MIT).codeRepository and issueTracker - where the code and issues live.programmingLanguage, softwareRequirements - stack and dependencies.identifier - the software's own DOI once archived.referencePublication - the related article, with its DOI as
identifier, when there is a paper to cite.funder - as an Organization with an identifier such as a Crossref
Funder ID.keywords, dateCreated, dateModified - discovery and freshness.
Generate it with the CodeMeta Generator (form-based) or SOMEF (from README
and docs), then always review it by hand to add ORCID iDs and funder detail,
and validate the JSON-LD.
Keep it current: update on every new version or contributor.
Identify and version the software
Uniquely identifying software and each version underpins reproducibility,
citation, and long-term access. Combine
methods rather than treating them as alternatives:
- Semantic Versioning (
MAJOR.MINOR.PATCH) for human-readable release
identity - apply it consistently across GitHub tags and distribution
artifacts like Docker images.
- A DOI for a globally unique, citable reference that plugs into academic
systems - the right choice for research software.
- Git commit hashes and cryptographic checksums for exact development
snapshots and integrity, where relevant.
If the project is registered in a repository or registry, a persistent
identifier is often created automatically; the awesome-research-software-
registries list helps find a suitable one.
Getting a DOI from Zenodo
Zenodo issues a concept DOI for the project as a whole plus a release
DOI per version - cite the release DOI for reproducibility, the concept DOI
to refer to the project generally.
For GitHub-hosted code:
- Create or link a Zenodo account to the GitHub account.
- Enable the repository under Zenodo's GitHub settings so each release is
archived automatically.
- Draft a new release on GitHub; Zenodo archives it and mints a DOI.
- Copy the DOI badge (Markdown form) into the repository README.
For GitLab-hosted code, the path differs:
provide a codemeta.json, get a Zenodo token with publishing scopes, and add
eOSSR or gitlab2zenodo to the GitLab CI pipeline so a release triggers an
automatic Zenodo deposit and DOI. Note gitlab2zenodo needs a .zenodo.json
converted from codemeta.json (eossr can do this).
Credit and recognition
Software contributions - maintenance, bug fixes, review, documentation - are
routinely invisible in publication-centric assessment. Making them creditable
needs structured metadata linking people to specific work via persistent
identifiers. Advise:
- Reward actions over roles: record verifiable, specific activities (a bug
fix, a feature, a test-suite improvement) rather than static labels like
"Developer". Still map roles with CRediT or the Contributor Roles Ontology
where automated systems or institutions need them.
- Get every contributor an ORCID so identity flows into professional records
without manual work.
- Make the software findable and citable via a DOI first - a contribution no
one can point to will not be counted.
- Prefer tools that capture credit automatically from the workflow: APICURON
for validated contribution events on ORCID profiles, BIP! Scholar for reuse
and popularity indicators from OpenAIRE Graph metadata.
For a career or assessment case, pair quantitative reach (package-manager
downloads on PyPI or CRAN, dependency graphs, citing papers) with narrative
on technical complexity and scientific impact; check whether the institution
or funder recognises software as an output; and add a "Credit and
Recognition" section to the Software Management Plan, tracking contributions
from the start rather than retrospectively.
Validate citation files in CI: the cffconvert GitHub Action checks
CITATION.cff on every push, so a malformed file fails fast instead of
surfacing at publication time (pattern from the NLeSC python-template).
Follow the contributors, proactively
Contributor records rot silently: people join, review, triage and
document, and the citation files still name the two founders. Track
contributions and suggest updates rather than waiting to be asked:
- Watch ALL contribution kinds, not just commits: merged PRs and
their reviewers, substantive issue triage, documentation and
support work - the all-contributors categories exist because
commit logs miss the classically uncredited work.
- Harvest authorship from commit METADATA: author/committer fields,
Co-authored-by: trailers and .mailmap are the machine-readable
record - names pasted into commit prose or file headers are not
(rseng-version-control-review); fix wrong-place practice at the
source before fixing citation files.
- Diff activity against
CITATION.cff, codemeta.json and
CONTRIBUTORS; report who is active but unrecorded (and recorded
but never active - possibly fine, possibly a paste error).
- Suggest at natural checkpoints: release prep (before the DOI
freezes the author list), citation-file edits, a contributor's
first merged PR.
- Respect policy and people: who counts as author vs acknowledged
contributor is project policy (rseng-community-governance); adding
someone needs their consent and preferred name/ORCID; never
remove or reorder without explicit agreement. The agent proposes
with evidence; humans decide.
- Automate the memory: the all-contributors bot records categorized
contributions as they happen; a release-checklist item makes the
check routine (rseng-publishing-releasing).
Credit what the code came from
Crediting flows both ways: the sources that INFORM generated or
hand-written code deserve the same rigor as the project's own
citability. Whenever a website, publication, algorithm description,
existing codebase, or a Q&A answer shapes code, record it in every
place a future reader will look:
- At the code site: a short comment where the adaptation lives -
source URL or DOI, what was taken (algorithm, approach, snippet),
and the source's license whenever actual code was copied or
ported. If code was copied, license compatibility must be checked
first (rseng-license-compliance); incompatible source license means
reimplement from the description, not copy.
- In the references: load-bearing sources - the paper whose method
the code implements, software that was adapted - belong in
CITATION.cff
references entries (type, title, authors, DOI/URL)
and in the project documentation's references section, not only
in a comment.
- In the AI declaration: when an agent generated the code, the
aidecl.yaml component notes name the sources it drew on
(rseng-ai-declaration) - provenance of the inputs, not just the
tool.
- Honestly: omitting a source that materially shaped the code
misrepresents the work's originality (rseng-honesty), and a cited
source must actually support what it is cited for
(rseng-fact-checking).
There is no file pattern that reveals an uncredited source, so no
mechanical check exists - this is a discipline to apply AT
GENERATION TIME, and a review question afterwards (rseng-code-review:
"where did this method come from, and does the code say so?").
Working with this skill
The generated references.md beside this file lists the source material
and pointers.
Learn more (verified):
<!-- related-skills:begin -->
Related skills
Check whether any of these applies before moving on:
- rseng-archiving - deposit metadata reuses codemeta
- rseng-citation-hygiene - verifying outbound references
- rseng-community-governance - authorship policy decisions
- rseng-fair-software - metadata implements findability
- rseng-publishing-releasing - DOI minting at release
- rseng-software-reuse - citing adopted software
- rseng-version-control-review - authorship harvested from commit metadata
<!-- related-skills:end -->