Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions docs/wiki-guide/GitHub-Repo-Guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ For more information on managing these environments and generating such files pr

### 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](#citation-templates).
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](#citation-templates) or use [OpenCite](https://imageomics.github.io/OpenCite/)[^2].

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.

Expand All @@ -116,7 +116,7 @@ Providing this file is as simple as copying the below example and filling in you
=== "Standard Citation File (Recommended)"

!!! tip "Pro tip"
Pair this citation file with a [`.zenodo.json`](#zenodo-metadata) for easier DOI metadata tracking (grants, references, associated papers).
Pair this citation file with a [`.zenodo.json`](#zenodo-metadata) for easier DOI metadata tracking (grants, references, associated papers). [OpenCite](https://imageomics.github.io/OpenCite/) can generate both files from one form with helpful previews to review the files before downloading them.

```yaml { py linenums="1" }
abstract: "<describe your code/package>"
Expand Down Expand Up @@ -150,7 +150,7 @@ Providing this file is as simple as copying the below example and filling in you
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).

!!! success "Simplify version tracking for you code"
Pair the [standard citation file](#__tabbed_1_1) with a [.zenodo.json file](#zenodo-metadata), which can track references, associated papers, and grant information.
Pair the [standard citation file](#__tabbed_1_1) with a [.zenodo.json file](#zenodo-metadata), which can track references, associated papers, and grant information. [OpenCite](https://imageomics.github.io/OpenCite/) can generate both files from one form with helpful previews to review the files before downloading them.

!!! info
- Subcategories of `preferred-citation` do not get bullet points, but the first subcategory of `references` must be bulleted (as below).
Expand Down Expand Up @@ -219,6 +219,8 @@ Providing this file is as simple as copying the below example and filling in you
Check whether your citation renders correctly on a branch. When you push the `CITATION.cff` to a branch and browse the repository at that branch, you can select "Cite this repository" in the righthand sidebar to see if it is rendering as expected:
![Screenshot of "Cite this repository" pop-up on the Collaborative Distributed Science Guide repository. It shows APA and BibTeX 'content tabs' with the beginnings of a scrollable and copiable citation](images/GH-repo-guide/citation-cff-check.png)

[^2]: [OpenCite](https://imageomics.github.io/OpenCite/) creates standardized citation metadata through a guided form for project details, authors, identifiers, references, and funding, which can be imported from a GitHub repository. It previews the generated `CITATION.cff` and `.zenodo.json` files, helping to avoid missing or inconsistent metadata when preparing for release and/or archive to Zenodo. Always review the generated or imported information for accuracy before adding the files to a repository or publishing a DOI.

## 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.
Expand All @@ -233,7 +235,7 @@ Contributing guidelines are important to maintain consistency across the way peo

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)). Alternatively, The example below can simply be copied into a new file and updated with the appropriate information (comments should be removed prior to upload).
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)). Alternatively, you can use [OpenCite](https://imageomics.github.io/OpenCite/)[^2] to generate both files together, or copy the example below into a new file and update it 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.
Expand Down
Loading