From 8f3e93858654a112a66a0913fae4849a95109765 Mon Sep 17 00:00:00 2001 From: Alex Ioannidis Date: Thu, 27 Nov 2025 10:52:41 +0100 Subject: [PATCH] fix(help/github): clarify resulting behavior of metadata files --- .../describe-software/citation-file/contents.lr | 9 ++++++++- .../docs/github/describe-software/contents.lr | 5 ++++- .../describe-software/zenodo-json/contents.lr | 15 ++++++++++++++- 3 files changed, 26 insertions(+), 3 deletions(-) diff --git a/content/help/docs/github/describe-software/citation-file/contents.lr b/content/help/docs/github/describe-software/citation-file/contents.lr index 67cefd1..d39ce7e 100644 --- a/content/help/docs/github/describe-software/citation-file/contents.lr +++ b/content/help/docs/github/describe-software/citation-file/contents.lr @@ -6,8 +6,15 @@ menu: /help/docs/github --- sort_key: 2 --- -body: +body: A `CITATION.cff` file can be added to your GitHub repository to describe the software after it is preserved in Zenodo. + +**Note:** If your repository also contains a `.zenodo.json` file, Zenodo will **only** use the `.zenodo.json` metadata and ignore the `CITATION.cff` entirely. However, we still recommend having a `CITATION.cff` file because GitHub uses it to display a [citation suggestion](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) on your repository page, making it easier for others to cite your software. + +**Looking forward:** Zenodo's long-term preference is for open metadata formats like `CITATION.cff` to eventually make the `.zenodo.json` format unnecessary. We hope to see the Citation File Format evolve in two directions: + +- **Broader metadata support:** Adoption of widely-used metadata attributes such as funding information. +- **Extension mechanisms:** Support for platform-specific extensions that would allow services like Zenodo to utilize custom attributes (such as specifying Zenodo communities). --- docs: #### docsheader #### diff --git a/content/help/docs/github/describe-software/contents.lr b/content/help/docs/github/describe-software/contents.lr index 7f32d11..8faf9bb 100644 --- a/content/help/docs/github/describe-software/contents.lr +++ b/content/help/docs/github/describe-software/contents.lr @@ -13,11 +13,14 @@ docs: text: The metadata schema used by Zenodo was extended with fields based on the [CodeMeta](https://codemeta.github.io/) standard, providing support for software-specific metadata. -Moreover, Zenodo supports `CITATION.cff` and `.zenodo.json` files for software releases originating from GitHub, enhancing the integration and making the content easier to cite. +Moreover, Zenodo supports `CITATION.cff` and `.zenodo.json` files for software releases originating from GitHub, enhancing the integration and making the content easier to cite. + +**Important:** If both files are present in your repository, **only** the `.zenodo.json` metadata will be used for the GitHub release archiving. The `CITATION.cff` metadata will be ignored by Zenodo. See the individual pages below for more details on when to use each format. Find more information about citing content on GitHub here: - [Referencing and citing content](https://docs.github.com/en/repositories/archiving-a-github-repository/referencing-and-citing-content) +- [About CITATION files](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) These are the supported methods to describe software records: #### docstoc #### diff --git a/content/help/docs/github/describe-software/zenodo-json/contents.lr b/content/help/docs/github/describe-software/zenodo-json/contents.lr index c14ddf0..442fa6c 100644 --- a/content/help/docs/github/describe-software/zenodo-json/contents.lr +++ b/content/help/docs/github/describe-software/zenodo-json/contents.lr @@ -6,8 +6,18 @@ menu: /help/docs/github --- sort_key: 3 --- -body: +body: A `.zenodo.json` file can be added to your GitHub repository to describe the software after it is preserved in Zenodo. + +**Note:** If your repository contains both a `.zenodo.json` and a `CITATION.cff` file, Zenodo will **only** use the `.zenodo.json` metadata. The `CITATION.cff` will be completely ignored for the GitHub release archiving. + +**Why use .zenodo.json?** The `.zenodo.json` format supports Zenodo-specific metadata that `CITATION.cff` does not yet support, such as: + +- **Funding information** via the `grants` field +- **Zenodo communities** via the `communities` field +- Other Zenodo-specific fields like `access_right`, `related_identifiers`, and contributor roles + +**If you don't need these Zenodo-specific features, a `CITATION.cff` file alone is sufficient.** --- docs: #### docsheader #### @@ -79,6 +89,9 @@ text: Find below an example of a `.zenodo.json` file: "language": "eng", "grants": [ {"id": "10.13039/501100000780::101122956"} + ], + "communities": [ + {"identifier": "simulation-software"} ] } ```