Pull upstream changes to Citation and Archiving with Zenodo

docs/wiki-guide/DOI-Generation.md

@@ -41,12 +41,7 @@ When your GitHub and Zenodo accounts are linked, there will be a list of availab
 
 When automatically generating a DOI with Zenodo, it uses information provided in your `CITATION.cff` file to populate the metadata for the record. However, there is important information that is not supported through this integration despite its inclusion in the `CITATION.cff` format in some cases.
 
-If your repository is likely to be updated repeatedly (i.e., generating new releases), then you may consider adding a `.zenodo.json` to preserve the remaining metadata on release sync with Zenodo for DOI. This metadata includes grant (funding) information, references (which may be included in your `CITATION.cff`), and a description of your repository/code.
-
-A `.zenodo.json` can be created by applying [cffconvert](https://github.com/citation-file-format/cffconvert) to your `CITATION.cff` (without the references, as these are not supported). Then add the references and other metadata back in to the JSON (following the [Zenodo dev guide](https://developers.zenodo.org/#representation)).
-The `publication_date` and `version` will need to be updated along with the `CITATION.cff` for each release.
-!!! example "Example `.zenodo.json`"
-    An example of this is the [Andromeda Zenodo JSON](https://github.com/Imageomics/Andromeda/blob/main/.zenodo.json). We also recommend including format tests following the example in this [PR](https://github.com/Imageomics/Andromeda/pull/120).
+If your repository is likely to be updated repeatedly (i.e., generating new releases), then you may consider adding a `.zenodo.json` to preserve the remaining metadata on release sync with Zenodo for DOI. This metadata includes grant (funding) information, references (which may be included in your `CITATION.cff`), associated paper(s), and a description of your repository/code. Details and a sample file structure are provided in the [Zenodo Metadata section](GitHub-Repo-Guide.md#zenodo-metadata) of the GitHub Repo Guide.
 
 _Alternatively_, this information can be updated manually on the Zenodo page for the DOI record. When logged in to Zenodo, a large orange "Edit" button will appear in the top right (as in the image below). There is the ability to save as you go (without publishing the metadata changes) and an additional option to share a link with collaborators to view the suggested record information.
 
@@ -61,12 +56,38 @@ _Alternatively_, this information can be updated manually on the Zenodo page for
 
 #### Manual Generation
 
-Building on the alternate edit options, there is also the option to simply generate one or all of your releases through a direct upload to Zenodo's site. Mixing the two methods is not advisable and may require reaching out to Zenodo to have them manually re-aligned to each other. Automatic generation through the GitHub integration is the recommended approach since it will generate an updated DOI on each release and create easier connections.
+Building on the alternate edit options, there is also the option to simply generate one or all of your releases through a direct upload to Zenodo's site. Automatic generation through the GitHub integration is the recommended approach since it will generate an updated DOI on each release and create easier connections.
+
+!!! warning
+    Do **not** mix the two methods. One must start with the GitHub integration, otherwise two separate records will be created. If a repo already has releases prior to turning on the GitHub integration, one can contact Zenodo to have them import the earlier releases as well. This is also another motivator for setting up the [requisite files in a GitHub repo](GitHub-Repo-Guide.md#zenodo-metadata) before the first release.
 
 #### Access Management
 
 When creating a new record on Zenodo, please ensure that other members of your project have access, as appropriate. In particular, there should be at least one member of Institute leadership or the Senior Data Scientist added to the record with management permissions. This ensures the ability to maintain the metadata and address matters related to the record (which may extend beyond your tenure with the Institute) in a timely manner.
 
+#### Add a Zenodo DOI Badge
+
+Congratulations, your repository has been archived on Zenodo! Now, how do you get the nice badge to display on your GitHub `README` so everyone knows it has been archived?
+
+1. Navigate to your account settings and select "GitHub" (see earlier screenshot at [automatic generation](#automatic-generation) for what the page looks like).
+
+2. Find the repo that has just been updated in the "Enabled Repositories" list (we'll use this guide's repo for the example), and click on the badge next to the repo's name:
+
+    ![Screenshot of GitHub Integration enabled repos with their DOI badges next to their names, the DOI badge next to the collaborative distributed science guide is circled](images/doi-generation/enabled_repos_badges.png)
+
+    The pop up will look something like this:
+
+    ![Screenshot of Zenodo DOI badge rendering options, only Markdown version fully shown: '[![DOI](https://zenodo.org/badge/1038590952.svg)](https://doi.org/10.5281/zenodo.17210328)'](images/doi-generation/badge-markdown.png)
+
+3. Copy the Markdown text and paste it next to your `README` title. Note that the DOI URL should be the _version agnostic_ DOI (this is the one you will add to your `CITATION.cff`, as noted in the [GitHub Repo Guide](GitHub-Repo-Guide.md#citation))
+
+    ![Screenshot of collaborative distributed science guide repo README file header in the GitHub UI with the badge text from above next to the title](images/doi-generation/README-badge-paste.png)
+
+This only has to be done once; using the version agnostic DOI with the general SVG means the badge will be updated to always display the DOI of the latest release and it will link to that Zenodo record.
+
+!!! warning
+    If you use the badge from the Zenodo page itself, it will be specific for _that_ version, so be sure to get the version agnostic one.
+
 ### 3. Generate a DOI with Dryad
 
 [Dryad](https://datadryad.org/stash/about) is another research data repository, similar to Zenodo, through which one can archive digital objects (such as, but not limited to, data) supporting scholarly publications, and obtain a DOI. It has a review process when depositing data and requires dedication to the public domain (CC0) of all digital objects uploaded. Imageomics through OSU is a member organization of Dryad, reducing or eliminating data deposit charge(s). To determine whether Dryad is a suitable archive for Institute data products supporting your publication, please consider the [Data Archive Options Comparative Overview](../pdfs/Data_Archive-Publication-Options-Comparative-Overview.pdf) for more information, and consult with the Institute's Senior Data Scientist.[^1]

docs/wiki-guide/GitHub-Repo-Guide.md

@@ -15,6 +15,7 @@ For each repository, include the following files in the root directory as soon a
 * [LICENSE.md](#license)
 * [.gitignore](#gitignore)
 * [software requirements](#software-requirements-file)
+* [CITATION.cff](#citation)
 
 More [recommendations](#recommended-files) are discussed below.
 
@@ -72,25 +73,18 @@ It is also advisable to include a machine-readable file with minimal software re
 
 For more information on managing these environments and generating such files programmatically, see the wiki entry [Virtual Environments](Virtual-Environments.md).
 
-## Recommended Files
-
-Though the following files are not included in every repository and do not have a simple selection process integrated into GitHub, they are extremely important (if not essential) to maintaining FAIR principles and reproducibility in projects, as well as ensuring proper attribution for your work.
-
-### CONTRIBUTING
-
-If you are looking to open your project to more public contributions, it is a good idea to include contributing guidelines. This could take the form of a "CONTRIBUTING.md" file or a subsection of your README.
-
-Contributing guidelines are important to maintain consistency across the way people work on a project. It is important to establish conventions about the important things while avoiding excessive constraints and bureaucracy that would make contributing a pain. Important things include efficient and effective communication.
-
 ### CITATION
 
 Make it easier for people to cite your project by including a [CITATION.cff file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files); you can copy-paste the template below.
 
-As with journal publications, we expect to be cited when someone uses our code. To facilitate proper attribution, GitHub will automatically read a [CITATION.cff file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) and display a link to "cite this repository". Providing this file is as simple as filling your information into one of their example files and uploading it to your repo. More examples and information about the Citation File Format can be found on the [citation-file-format repo](https://github.com/citation-file-format/citation-file-format), including helpful [related tools](https://github.com/citation-file-format/citation-file-format#tools-to-work-with-citationcff-files-wrench).
+As with journal publications, we expect to be cited when someone uses our code. To facilitate proper attribution, GitHub will automatically read a [CITATION.cff file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) and display a link to "cite this repository". This file is also used to populate metadata fields in a [Zenodo](https://zenodo.org/) record when [auto-generating a DOI](DOI-Generation.md#2-generate-a-doi-with-zenodo). As with any other component of your project, this file may change over the project's lifespan (see [Digital Product Life Cycle](Digital-Product-Lifecycle.md) for details), but it should be present and updated before any release.
+
+Providing this file is as simple as copying the below example and filling in your information before uploading it to your repo. More examples and information about the Citation File Format can be found on the [citation-file-format repo](https://github.com/citation-file-format/citation-file-format), including helpful [related tools](https://github.com/citation-file-format/citation-file-format#tools-to-work-with-citationcff-files-wrench).
 
 You can check your CITATION.cff file prior to upload using this [validator tool](https://www.yamllint.com/).
 
 !!! note "Note"
+    - When adding a DOI to your citation (`doi`), be sure to use the version-agnostic DOI from Zenodo. Since the DOI is not generated until _after_ the release, this ensures there will never be an "incorrect" DOI associated to the release—correct version reference is ensured through the `version` key, which should always be updated _**before**_ generating a new release.
     - Subcategories of `preferred-citation` do not get bullet points, but the first subcategory of `references` must be bulleted (as below).
     - This is generally intended as a reference for your code. Preferred citation can be used for the paper, though it is better to ask in the `README` that someone cites _both_ and provide the paper reference there (only the `preferred-citation` will show up to be copied from the citation box if it is included).
 
@@ -116,7 +110,7 @@ message: "If you find this software helpful in your research, please cite both t
 repository-code: "https://github.com/Imageomics/<repo>"
 title: "<repo title>"
 version: <release version>
-doi: <DOI from Zenodo>
+doi: <DOI from Zenodo>    # version agnostic DOI
 type: software
 preferred-citation:
   type: article
@@ -142,6 +136,58 @@ references:
     date-released:
 ```
 
+## Recommended Files
+
+Though the following files are not included in every repository and do not have a simple selection process integrated into GitHub, they are extremely important (if not essential) to maintaining FAIR principles and reproducibility in projects, as well as ensuring proper attribution for your work.
+
+### CONTRIBUTING
+
+If you are looking to open your project to more public contributions, it is a good idea to include contributing guidelines. This could take the form of a "CONTRIBUTING.md" file or a subsection of your README.
+
+Contributing guidelines are important to maintain consistency across the way people work on a project. It is important to establish conventions about the important things while avoiding excessive constraints and bureaucracy that would make contributing a pain. Important things include efficient and effective communication.
+
+### Zenodo Metadata
+
+When using the Zenodo-GitHub integration for [automatic DOI generation](DOI-Generation.md#automatic-generation), tracking metadata beyond the basics (authors, keywords, title, etc.) requires manual updates to the Zenodo record. The solution for this is to include a `.zenodo.json` file to keep track of this information (e.g., grant funding and references).
+
+A `.zenodo.json` can be created by applying [cffconvert](https://github.com/citation-file-format/cffconvert) to your `CITATION.cff` (without the references, as these are not supported). Then add the references and other metadata back in to the JSON (following the [Zenodo dev guide](https://developers.zenodo.org/#representation)). Alterntatively, The example below can simply be copied into a new file and updated with the appropriate information (comments should be removed prior to upload).
+
+!!! note
+    The `publication_date` and `version` will need to be updated along with the `CITATION.cff` for each release.
+
+```json
+{
+    "creators": [
+      {
+          "name": "family-names, given-names",
+          "orcid": "",
+          "affiliation": ""
+      },
+      {
+          "name": "family-names, given-names",
+          "orcid": "",
+          "affiliation": ""
+      }
+    ],
+    "description": "", // Ex: abstract from the citation, HTML can be used for formatting
+    "keywords": [  // Add the same list of keywords as in your CITATION.cff
+      "imageomics"
+    ],
+    "title": "<repo title>",
+    "version": "<release version>",
+    "license": "<license>",           // Check docs for codes: https://developers.zenodo.org/#representation
+    "publication_date": "YYYY-MM-DD",
+    "grants": [
+        {
+            "id": "021nxhr62::2118240"  // Imageomics (<NSF code>::<Imageomics Grant #>)
+        }
+    ] 
+}
+```
+
+!!! example "Example `.zenodo.json`"
+    The [Zenodo JSON for BioCLIP 2](https://github.com/Imageomics/bioclip-2/blob/main/.zenodo.json) provides an example that includes a grant, references, and an associated paper (`related_identifiers`), which is also listed under `notes` [for additional citation](https://zenodo.org/records/17049307). We also recommend including [this format validation workflow](https://github.com/Imageomics/Collaborative-distributed-science-guide/blob/main/.github/workflows/validate-zenodo.yaml), which will run if either the `.zenodo.json` or the workflow itself is edited.
+
 ## Additional Considerations
 
 ### Formatting and Naming Conventions