You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: publish-share-code/cite-code.md
+44-71Lines changed: 44 additions & 71 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,20 +16,20 @@ kernelspec:
16
16
(cite-your-code)=
17
17
# Ways to Add a Citation to Your Code
18
18
19
-
[Sharing](share-your-code) and making your code **citable**helps others **acknowledge your work, build upon it, and give you proper credit**.
19
+
[Sharing](share-your-code) and making your code **citable**supports others **acknowledge your work, build upon it, and give you credit**. Citation further supports making workflows open and documenting all parts of the scientific process.
20
20
21
-
Citations ensure that code, software, and data receive proper recognition as part of the open scientific process. Others can easily credit your work and trace research outputs by citing your code.
22
21
23
-
:::{tip}
24
-
<iclass="fa-solid fa-rocket"></i> Want to maximize your code’s impact? **Host it on [GitHub or GitLab](share-your-code) with an [open license](open-license) and make it citable.**
25
-
:::
22
+
:::{admonition} What you will learn
23
+
:class: note
26
24
25
+
* How to create a DOI using Zenodo and GitHub
26
+
* How to create a citation file to use on GitHub
27
+
* What a DOI is
28
+
:::
27
29
28
-
In this lesson, you will learn:
29
30
30
-
1. How to create a DOI using Zenodo and GitHub
31
-
2. How to create a citation file to use on GitHub
32
-
1. What a a DOI is
31
+
<iclass="fa-solid fa-rocket"></i> This lesson assumes that your code is already **hosted on [GitHub or GitLab](share-your-code) with an [open license](open-license).**
32
+
:::
33
33
34
34
(zenodo)=
35
35
## What is Zenodo?
@@ -45,7 +45,7 @@ pyOpenSci has a [Zenodo community](https://zenodo.org/communities/pyopensci/reco
45
45
46
46
### How does Zenodo work?
47
47
48
-
Zenodo makes it easy to create a **DOI** for your GitHub repository, ensuring your code is **citable and discoverable**. To create a DOI for your repo you need to:
48
+
[Zenodo](https://zenodo.org/) makes creating a **DOI** for your GitHub repository easy, ensuring your code is **citable and discoverable**. To create a DOI for your repo, you need to:
49
49
50
50
1. <iclass="fas fa-link"style="color:#81c0aa;"></i> **Link your GitHub account** to Zenodo.
51
51
2. <iclass="fas fa-cogs"style="color:#81c0aa;"></i> **Enable your repository** in Zenodo’s settings.
@@ -55,9 +55,9 @@ Each release gets a unique DOI, while the repository keeps a persistent record,
55
55
56
56
## How to create a DOI for a Python package on GitHub
57
57
58
-
### Step 1: Setup Zenodo
58
+
### Step 1: Login to Zenodo
59
59
60
-
1. Go to zenodo.org and sign in using your GitHub account
60
+
1. Go to [zenodo.org](https://zenodo.org/) and sign in using your GitHub account
61
61
2. Go to your profile drop-down and select “GitHub
62
62
63
63
@@ -69,37 +69,31 @@ You should see a screen like the one below. If you‘ve never used Zenodo before
69
69
:::
70
70
71
71
72
-
When you select GitHub you might see a list of repositories if you've used Zenodo before or if it finds your repos automagically. Don't worry if you don't see that list yet, you may have to sync your account with GitHub.
72
+
When you go to the Zenodo GitHub page, you will see a list of repositories if you've used Zenodo before and synced your repos. If you haven't yet synced them, read on to learn how.
Go to your account drop down and click on GitHub. You will see a list of repositories that you have access to. Click the Sync Now button to update that list.
79
78
:::
80
79
81
-
Click the sync now button in the get started page to update your list of GitHub repos. The more repositories that you have access to, the longer this will take. It’s normal for it to take a few minutes and maybe 5 minutes or more.
80
+
### Step 2. <iclass="fa-solid fa-arrows-rotate"></i> Sync your GitHub repos
82
81
83
-
:::{figure} /images/zenodo/zenodo-sync-repos.png
84
-
:alt: text
82
+
Click the <kbd><iclass="fa-solid fa-arrows-rotate"></i> Sync Now</kbd> button in the **<iclass="fa-brands fa-github"></i> Get started** section of the page to update the displayed list of GitHub repos. The repos that Zenodo fetches are the ones that you have ownership of or write access to.
85
83
84
+
The more repositories that you have access to, the longer the sync process will take. It’s normal for it to take a few minutes and maybe 5 minutes or more.
86
85
87
-
:::
88
86
89
87
:::{tip}
90
88
If you have access to many GitHub repositories through both your own account and other organization accounts that you may have access too, the sync button may take a long time to run. It could take 5 minutes or more for someone with hundreds to thousands of repos). Be patient.
91
89
:::
92
90
93
-
Once your repos are synced, it's time to "flip the switch" or turn on a connection between GitHub and Zenodo for your Python package.
91
+
### Step 3. <iclass="fa-solid fa-toggle-off"></i> Flip the switch <iclass="fa-solid fa-toggle-on"></i>
Once your repos are synced, you can "<iclass="fa-solid fa-toggle-off"></i> flip the switch <iclass="fa-solid fa-toggle-on"></i>" or turn on a connection between GitHub and Zenodo for your Python package.
* Click the <kbdstyle="background-color: #238636; color:#fff; padding:.5em;">Create new release</kbd> button
124
+
* Create a new tagged release
134
125
135
-
You can either generate automatic release notes or type in notes yourself. Either is acceptable but for convenience today you could opt to generate release notes for this release!
126
+
You can generate automatic release notes or type in notes yourself.
136
127
137
-
When you are ready, scroll to the bottom of the page and click "publish release" When you publish your release, Zendo will begin to do its job—generating a DOI for the repository and the release and processing the metadata for the release.
128
+
*When you are ready to publish your release, scroll to the bottom of the page and click <kbdstyle="background-color: #238636; color:#fff; padding:.5em;">Publish Release</kbd>. When you publish your release, Zendo will begin to do its job—generating a DOI for the repository and the release and processing the metadata for the release.
Once you are ready, you can create a release. Once you have created the release, zenodo will process it and create a badge for your repository. Notice that this screen cast is for a repo where a release already exists. The process is the same whether you have a release already or not!
143
134
:::
144
135
145
-
### Step 3: Get your zenodo badge and add it to your project README file
136
+
### Step 5: Add your Zenodo badge in markdown to your project README file
146
137
147
-
Add your zenodo badge to your readme file in your repo!
148
-
Important: be sure to use the cite all versions badge.
138
+
After you create a release, you will see a badge on the Zenodo website. If you click on it, it will provide you with a copyable badge format for markdown and other formats. Copy the badge in markdown format. You will add this to your readme file.
149
139
150
-
151
-
AFTER YOU CREATE a release, you will see a badge on the Zenodo website. If you click on it, it will provide you with a copyable badge format for markdown and other formats. Copy the badge in markdown format. You will add this to your readme file.
140
+
:::{important}
141
+
Be sure to use the cite-all versions badge, which will always resolve to the most current DOI rather than a specific point in time.
142
+
:::
152
143
153
144
:::{figure} /images/zenodo/zenodo-badge.png
154
145
:alt: text
155
146
156
-
147
+
Once you have created a GitHub release, you will see a badge next to the repository with a DOI. You can click on that badge to get a copy-able markdown version of the rendered badge that you can add to your README file.
157
148
:::
158
149
159
150
160
-
##About citation.cff files
151
+
### Step 6: Optional--Add your DOI to the GitHub repo: the citation.cff file
161
152
162
-
Now that you have a DOI, add a CITATION.cff file to make it easy for others to cite your package.
153
+
Now that you have a DOI, add a [CITATION.cff](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) file to your GitHub repository to make it easy for others to cite your package.
163
154
Once you have a DOI, you can add a [citation.cff file](https://citation-file-format.github.io/) to your GitHub or GitLab repository. A `CITATION.cff` file standardizes citation information, making it easy for others to cite your work correctly.
164
155
165
156
166
157
167
-
To understand citations, it's important to understand what a DOI is.
168
-
169
158
## What is a DOI?
170
159
171
160
A **DOI**, or **Digital Object Identifier**, is a unique, permanent identifier assigned to digital content such as academic papers, datasets, software, and other research outputs. It acts like a stable web link that always directs users to the reference content, even if the location of the content changes. DOIs are commonly used in academic publishing to ensure that citations remain valid and materials are easily accessible. But you can also assign DOIs to software, data, and other research outputs and supporting elements.
@@ -190,22 +179,6 @@ The Journal of Open Source Software (JOSS), [a pyOpenSci partner](https://www.py
190
179
191
180
***Zenodo DOI**: Zenodo allows you to create DOIs for a wider range of digital content, including datasets, software (like your GitHub repositories), preprints, and event presentations. Zenodo is perfect for making your code or data citable, even if it’s not part of a formal publication.
192
181
193
-
Both types of DOIs ensure your work is easily found and cited. CrossRef is more focused on formal publications. While Zenodo offers more flexibility by covering a broader range of research outputs.
182
+
Both types of DOIs ensure that your work is easily found and cited. CrossRef is more focused on formal publications. Zenodo offers more flexibility by covering a broader range of research outputs.
194
183
195
184
By using the right DOI for your work, you help others find and cite it easily, no matter where or how it’s shared!
196
-
197
-
198
-
199
-
200
-
201
-
The video below walks you through how to set this all up.
202
-
203
-
:::{admonition}21 October 2024
204
-
:class: important
205
-
This video is a draft. It will be updated over the next two months, and a more polished version will be available soon.
0 commit comments