Skip to content

Commit 5021804

Browse files
egrace479egrace479
committed
Revise Citation section of GH repo guide
Pull from Collab Guide [PR 69](Imageomics/Collaborative-distributed-science-guide#69) * Restructure citation template section for improved clarity set up a standard vs extended citation also adds references as a key in Zenodo metadata template, with citation pointer recommending use there * Add support for content tabs used for citation CFF templates * Use conference-paper as default for preferred-citation include examples and exlanations for keys * fix formatting for citation file examples * Shorten note before template citation files Move preferred-citation notes to tab where it's included * Replace note about yaml validator tool with note to check format on branch validator tool checks yaml, not citation cff format * Create a subsubsection for citation templates, reduce admonition use to avoid clutter * Fix formatting of ORCID field * Clarify use of ORCID number only for zenodo JSON, different from CFF field * Add comment about when to update commit hash
1 parent 7191d5f commit 5021804

2 files changed

Lines changed: 112 additions & 54 deletions

File tree

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

Lines changed: 110 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -101,66 +101,119 @@ For more information on managing these environments and generating such files pr
101101

102102
### CITATION
103103

104-
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.
104+
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).
105105

106106
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.
107107

108108
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).
109109

110-
You can check your `CITATION.cff` file prior to upload using this [validator tool](https://www.yamllint.com/).
110+
#### Citation Templates
111111

112-
!!! note "Note"
113-
- 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.
114-
- Subcategories of `preferred-citation` do not get bullet points, but the first subcategory of `references` must be bulleted (as below).
115-
- 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-
117-
```yaml { py linenums="1" }
118-
abstract: "<describe your code/package>"
119-
authors:
120-
- family-names:
121-
given-names: "<First M.I.>"
122-
orcid: "https://orcid.org/<ORCID #>"
123-
cff-version: 1.2.0
124-
date-released: "YYYY-MM-DD"
125-
identifiers:
126-
- description: "The GitHub release URL of tag <version>."
127-
type: url
128-
value: "https://github.com/ABC-Center/<repo>/releases/tag/<tag-name>"
129-
- description: "The GitHub URL of the commit tagged with <tag-name>."
130-
type: url
131-
value: "https://github.com/ABC-Center/<repo>/tree/<commit-hash>"
132-
keywords:
133-
- biodiversity
134-
license:
135-
message: "If you find this software helpful in your research, please cite both the software and our paper."
136-
repository-code: "https://github.com/ABC-Center/<repo>"
137-
title: "<repo title>"
138-
version: <release version>
139-
doi: <DOI from Zenodo> # version agnostic DOI
140-
type: software
141-
preferred-citation:
142-
type: article
143-
authors:
112+
- 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&mdash;correct version reference is ensured through the `version` key, which should always be updated _**before**_ generating a new release.
113+
- A `CITATION.cff` is intended as a reference for your code; ask in the `README` that someone cites _both_ the repo and your paper, then provide the paper BibTeX there.
114+
- Formatted display can be checked on a branch before merging to `main`.
115+
116+
=== "Standard Citation File (Recommended)"
117+
118+
!!! tip
119+
Pair this citation file with a [`.zenodo.json`](#zenodo-metadata) for easier DOI metadata tracking (grants, references, associated papers).
120+
121+
```yaml { py linenums="1" }
122+
abstract: "<describe your code/package>"
123+
authors:
144124
- family-names:
145-
given-names:
125+
given-names: "<First M.I.>"
126+
orcid: "https://orcid.org/<ORCID #>"
127+
cff-version: 1.2.0
128+
date-released: "YYYY-MM-DD"
129+
identifiers:
130+
- description: "The GitHub release URL of tag <version>."
131+
type: url
132+
value: "https://github.com/ABC-Center/<repo>/releases/tag/<tag-name>"
133+
- description: "The GitHub URL of the commit tagged with <tag-name>."
134+
type: url
135+
value: "https://github.com/ABC-Center/<repo>/tree/<commit-hash>" # Update on release
136+
keywords:
137+
- imageomics
138+
license:
139+
message: "If you find this software helpful in your research, please cite both the software and our paper."
140+
repository-code: "https://github.com/ABC-Center/<repo>"
141+
title: "<repo title>"
142+
version: <release version>
143+
#doi: <version-agnostic DOI from Zenodo>
144+
type: software
145+
```
146+
147+
=== "Extended `CFF` (References and Citation redirect)"
148+
149+
!!! warning
150+
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).
151+
152+
!!! success "Simplify version tracking for you code"
153+
Pair the [standard citation file](#__tabbed_1_1) with a [.zenodo.json file](#zenodo-metadata), which can track references, associated papers, and grant information.
154+
155+
!!! info
156+
- Subcategories of `preferred-citation` do not get bullet points, but the first subcategory of `references` must be bulleted (as below).
157+
- If including `references` or setting a `preferred-citation`, see this [bibtex to cff crosswalk](https://docs.ropensci.org/cffr/articles/bibtex-cff.html#fieldskey-crosswalk) for help in translating a BibTeX citation to the proper `CFF` format.
158+
159+
```yaml { py linenums="1" }
160+
abstract: "<describe your code/package>"
161+
authors:
146162
- family-names:
147-
given-names:
148-
title:
149-
year:
150-
journal:
151-
doi:
152-
references:
153-
- authors:
154-
- family-names:
155-
given-names:
156-
- family-names:
157-
given-names:
158-
title:
159-
version:
160-
type:
161-
doi:
162-
date-released:
163-
```
163+
given-names: "<First M.I.>"
164+
orcid: "https://orcid.org/<ORCID #>"
165+
cff-version: 1.2.0
166+
date-released: "YYYY-MM-DD"
167+
identifiers:
168+
- description: "The GitHub release URL of tag <version>."
169+
type: url
170+
value: "https://github.com/ABC-Center/<repo>/releases/tag/<tag-name>"
171+
- description: "The GitHub URL of the commit tagged with <tag-name>."
172+
type: url
173+
value: "https://github.com/ABC-Center/<repo>/tree/<commit-hash>" # Update on release
174+
keywords:
175+
- imageomics
176+
license:
177+
message: "If you find this software helpful in your research, please cite both the software and our paper."
178+
repository-code: "https://github.com/ABC-Center/<repo>"
179+
title: "<repo title>"
180+
version: <release version>
181+
#doi: <version-agnostic DOI from Zenodo>
182+
type: software
183+
# Only include the following if you want to present the paper citation instead of code on sidebar,
184+
# Better to include paper citation in README
185+
preferred-citation:
186+
type: conference-paper
187+
authors:
188+
- family-names:
189+
given-names:
190+
- family-names:
191+
given-names:
192+
collection-title: # "Proceedings of the ..."
193+
collection-type: proceedings
194+
conference:
195+
name: # Name of conference, e.g., "ICLR 2025"
196+
pages: #"<start>-<end>"
197+
start: # First page, int
198+
end: # Last page, int
199+
title: # Paper title
200+
year:
201+
doi:
202+
# url: use only if DOI not available
203+
# References can be added here, but will only be read from the .zenodo.json file
204+
# Below example set to reference code repo, `preferred-citation` types apply
205+
references:
206+
- authors:
207+
- family-names:
208+
given-names:
209+
- family-names:
210+
given-names:
211+
title:
212+
version:
213+
type:
214+
doi:
215+
date-released:
216+
```
164217

165218
## Recommended Files
166219

@@ -186,7 +239,7 @@ A `.zenodo.json` can be created by applying [cffconvert](https://github.com/cita
186239
"creators": [
187240
{
188241
"name": "family-names, given-names",
189-
"orcid": "",
242+
"orcid": "", // Just the ORCID number, not the URL
190243
"affiliation": ""
191244
},
192245
{
@@ -207,7 +260,10 @@ A `.zenodo.json` can be created by applying [cffconvert](https://github.com/cita
207260
{
208261
"id": "021nxhr62::2330423" // ABC NSF grant, NSERC requires manual update
209262
}
210-
]
263+
],
264+
"references": [
265+
// list of references as strings in APA or similar format
266+
]
211267
}
212268
```
213269

‎mkdocs.yaml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,8 @@ markdown_extensions:
9292
- pymdownx.inlinehilite
9393
- pymdownx.snippets
9494
- pymdownx.superfences
95+
- pymdownx.tabbed:
96+
alternate_style: true
9597
- pymdownx.tasklist
9698
- pymdownx.tilde
9799
- pymdownx.keys

0 commit comments

Comments
 (0)