# CITATION.cff: [Software name]

> A ready-to-copy `CITATION.cff` file that tells people how to cite your research software or dataset, written in Citation File Format (CFF) 1.2.0, the current release of the format (checked 30 October 2026). Replace every `[bracketed]` value and every line marked *Example*. Worked examples use tidecalc, a fictional tide-modelling package from the fictional Westmere Institute for Coastal Research.

<!--
Guidance: How to use this template
- Save the YAML in section 2 as `CITATION.cff` in the root of the repository, on the default branch. GitHub then shows a "Cite this repository" link with APA and BibTeX output.
- Fill the four required keys first: `cff-version`, `message`, `title`, `authors`. Everything else is optional but makes the citation more useful.
- Update `version` and `date-released` with every release, in the same commit as the changelog (`dev/changelog`).
- For a software paper, add `preferred-citation` so that people cite the paper and not only the code.
-->

## 1. Before you write

<!-- Guidance: Decide who the authors are with the whole team before publishing. Changing an author list later causes old and new citations to disagree. -->

| Decision | Your answer |
|---|---|
| Who counts as an author | [*Example:* Everyone with substantial code, design or documentation contributions; minor contributors are thanked in the README] |
| Identifier to cite | [*Example:* An archive DOI minted per release; a concept DOI for "all versions"] |
| Preferred citation | [Software itself / A paper about the software] |
| Licence (SPDX identifier) | [*Example:* MIT] |

## 2. The file

<!-- Guidance: Quote every string that contains a colon, starts with a bracket or looks like a number or date you do not want parsed as one. Keep `date-released` as YYYY-MM-DD. -->

Copy the block below, then replace every bracketed value, including the brackets. Delete the `preferred-citation` block if there is no paper, and the `identifiers` block until the first archived release has a DOI.

```yaml
cff-version: 1.2.0
message: "If you use this software, please cite it using the metadata below."
type: software
title: "tidecalc: harmonic tide prediction for coastal stations"
version: "[2.1.0]"
date-released: "[YYYY-MM-DD]"
license: MIT
repository-code: "https://github.com/[owner]/tidecalc"
abstract: "tidecalc predicts tides from harmonic constituents and compares predictions with gauge records."
keywords:
  - oceanography
  - tides
  - time series
authors:
  - family-names: "[Family name]"
    given-names: "[Given names]"
    orcid: "https://orcid.org/[0000-0000-0000-0000]"
    affiliation: "Westmere Institute for Coastal Research"
  - family-names: "[Family name]"
    given-names: "[Given names]"
    affiliation: "Westmere Institute for Coastal Research"
  - name: "The tidecalc contributors"
identifiers:
  - type: doi
    value: "[10.xxxx/archive-record-for-this-release]"
    description: "Archived release of this version"
preferred-citation:
  type: article
  title: "[Title of the software paper]"
  authors:
    - family-names: "[Family name]"
      given-names: "[Given names]"
  journal: "[Journal name]"
  year: 2026  # replace with the publication year
  doi: "[10.xxxx/paper-doi]"
```

## 3. Key reference

<!-- Guidance: These are the keys most projects need. The full list, including datasets and references to other works, is in the CFF schema guide. -->

| Key | Required | What to put in it |
|---|---|---|
| `cff-version` | Yes | `1.2.0` |
| `message` | Yes | A short instruction to the reader on how to use the metadata |
| `title` | Yes | The name of the software or dataset |
| `authors` | Yes | People (`family-names`, `given-names`, optional `orcid`, `affiliation`) or entities (`name`) |
| `type` | No | `software` (default) or `dataset` |
| `version`, `date-released` | No | The release this file describes; date as YYYY-MM-DD |
| `identifiers` | No | Each with `type` (`doi`, `url`, `swh` or `other`) and `value` |
| `license` | No | An SPDX licence identifier, or a list read as "any of these" |
| `preferred-citation` | No | A reference object; needs at least `type`, `title` and `authors` |

## 4. Check and publish

<!-- Guidance: Validate before each release; if the file does not parse, GitHub shows an error on the file instead of the citation box. -->

- Validate the file with a CFF tool such as `cffconvert` (cff-converter-python), which can also export BibTeX, RIS and CodeMeta, or build it with the cffinit web form.
- If you archive releases through the Zenodo and GitHub integration, Zenodo reads `CITATION.cff` to fill the record; check the result after the first release.
- Link the file from the README Citation section (`dev/readme-full`) and from a replication package (`academic/replication-package-readme`) when the software supports a paper.

## Standard and licence note

Based on the Citation File Format 1.2.0 specification and schema guide (citation-file-format.github.io and github.com/citation-file-format/citation-file-format, released 9 August 2021, specification licensed CC BY 4.0), checked 30 October 2026. Key names are given as the format defines them; the example and wording are original. tidecalc and the Westmere Institute for Coastal Research are fictional; replace every identifier with your own and never invent a DOI or ORCID. Template licence: MIT.