index.qmd

---
title: "Publishing Code"
subtitle: "Using GitHub releases and Zenodo DOIs<br>to create citable code snapshots"
author: 
   - name: Stephen Formel
     orcid: 0000-0001-7418-1244
     affiliations:
        - name: "<img src='assets/the_data_patch_logo.png' style='height:60px; vertical-align:middle; margin-left:5px;'>"
date: "2026-01-29"
format:
  revealjs:
    title-slide-attributes:
      data-presentation-context: "Ocean Data Stewardship | Rutgers Operational Oceanography Program | Session #3"

---

## Examples

![](assets/instrument.png){width=100 style="vertical-align: middle;"} _Instrument: [Low-Cost Water Sampler](https://doi.org/10.5281/zenodo.10257622)_ ![](assets/watersampler.jpeg){width=150 style="vertical-align: middle;"}

![](assets/pipeline.png){width=100 style="vertical-align: middle;"} _Pipeline: [eDNA analysis](https://doi.org/10.5281/zenodo.8144154)_ ![](assets/Tourmaline.png){width=200 style="vertical-align: middle;"}

![](assets/analysis.png){width=100 style="vertical-align: middle;"} _Analysis: [Biodiversity Indicators](https://doi.org/10.5281/zenodo.15113966)_ ![](assets/H3.png){width=120 style="vertical-align: middle;"}

![](assets/documentation-svgrepo-com.png){width=100 style="vertical-align: middle;"} _Documentation: [Workshop](https://doi.org/10.5281/zenodo.7401979)_ ![](assets/smbd_workshop.png){width=150 style="vertical-align: middle;"}

## Why publish code? 

::: columns

<br> 

::: column
### Better World
![](assets/science_around_the_world.png){width=130 .float-left}
![](assets/fair.png){width=300}

:::

::: column
### Better Future
![](assets/content_person.png){width=80 .float-left}
<div class="small-text">
_make life easier!_
<br>
_reduce self-loathing!_
</div>
:::
:::

<br>

::: columns

::: column
### Enable Science
![](assets/tetris.png){width=80 .float-left}
<div class="small-text">
_drive reuse!_
<br>
_and extension!_
</div>
:::

::: column
### Get Credit
![](assets/get_credit.png){width=80 .float-left}
<div class="small-text">
_credit is the currency of science!_
<br>
_mo' money, less problems!_
</div>
:::

:::

::: notes
Timing: 2 min  
Set expectations. This is about concepts first, mechanics second.  
Emphasize that this mirrors data publishing practices participants may already know.
1. Increase FAIR-ness
2. Make life easier for future you
3. Enable reuse and extension
4. Get credit for software as a research output
:::

---

## The long view: a haiku.

::: columns

::: column
<br>
<div style="text-align: center;">
_science lives when tools_

_fade. Links rot but snapshots save_

_your work from the void_
</div>
:::

::: column
<div style="border-radius: 10px; overflow: hidden; box-shadow: 0 4px 14px rgba(0,0,0,0.15); display: inline-block; text-align: center; padding-top: 14px; margin-bottom: -20px;">
<iframe width="800" height="280" 
  src="https://www.youtube.com/embed/CZzQhiNQXxU?autoplay=1&mute=1&start=25" 
  allow="autoplay; encrypted-media" 
  allowfullscreen>
</iframe>
<div style="font-size: 0.4em; margin-top: -35px;">
<span style="display: block;">Whale Fall Actively Devoured by Scavengers at Davidson Seamount, Nautilus Live (2019)</span>
<span style="display: block; font-size: 0.8em;"><a href="https://www.youtube.com/watch?v=CZzQhiNQXxU">https://www.youtube.com/watch?v=CZzQhiNQXxU</a></span>
</div>
</div>
:::

:::

::: notes
Timing: 1 min 
Science outlives tools and platforms.
Papers persist. Links rot.
Without snapshots, methods cannot be verified.
:::


---

## <img src="https://cdn.simpleicons.org/github/white" width="225" style="vertical-align: middle;"/> GitHub is not an archive

- _Excellent for collaboration_
- _No preservation guarantee_
- _Not designed for citation_
- _owned by private corporation (Microsoft)_

::: notes
Timing: 1 min  
Be explicit that this is not anti-GitHub.  
GitHub does its job very well. It just does not do this job.
:::

---

## What is a code archive?
![](assets/archive.png){width=200 .float-left} 

<br>
_Persistent and referenced via PID_

_Findable and citable_

_Immutable once published_

_Backed by long-term infrastructure_

::: notes
Timing: 1 min  
:::

---

## <img src="https://about.zenodo.org/static/img/logos/zenodo-gradient-round.svg" width="400" style="vertical-align: middle;"/> (for code)

_Generalist research repository_

_Free and widely used_

_Issues DOIs via DataCite_

_Integrates with GitHub releases_

_operated by CERN_

::: notes
Timing: 1 min  
Do not go deep here. Zenodo is familiar enough.  
We are focusing on the GitHub integration.
CERN == European Organization for Nuclear Research, an intergovernmental organization funded by 23 member states
:::

---

## <img src="https://cdn.simpleicons.org/github/white" width="225" style="vertical-align: bottom;"/> + <img src="https://about.zenodo.org/static/img/logos/zenodo-gradient-round.svg" width="400" style="vertical-align: middle;"/> model
<br>
_GitHub: active development | where code lives_

_Zenodo: frozen snapshots | where code is cited_

::: notes
Timing: 1 min  
:::

---

## Where will you use this?

![](assets/instrument.png){width=100 style="vertical-align: middle;"} _Instrument development_

![](assets/pipeline.png){width=100 style="vertical-align: middle;"} _Pipeline development_

![](assets/analysis.png){width=100 style="vertical-align: middle;"} _Analysis iteration_

![](assets/documentation-svgrepo-com.png){width=100 style="vertical-align: middle;"} _Code-based documentation_

::: notes
Timing: 2 min  
Ask students to come up with examples
:::

---

## Versioning and DOIs

_Each GitHub release → new Zenodo version_

_Each version gets its own ![](https://upload.wikimedia.org/wikipedia/commons/1/11/DOI_logo.svg){width=60 style="vertical-align: middle;"}_

_One parent 'concept' ![](https://upload.wikimedia.org/wikipedia/commons/1/11/DOI_logo.svg){width=60 style="vertical-align: middle;"} always points to the latest version_

::: notes
Timing: 2 min  
This mirrors the Zenodo versioning explanation from the dataset clinic.  
:::

---

## Let's Practice

## Pre-work: 

_did you make a_ <img src="https://cdn.simpleicons.org/github/white" width="100" style="vertical-align: middle;"/> _account?_

_If not, do it <a href="https://docs.github.com/en/get-started/start-your-journey/creating-an-account-on-github">here</a>_

::: notes
Timing: 3 min
Set clear expectations: this is a hands-on exercise.
Encourage participants to ask questions if stuck at any step.
Put a thumbs up in shared notes for each step when you're ready to move on
:::

---

## Step 1: Fork the Repository

1. Go to the example repo on GitHub (https://github.com/the-data-patch/do-watcha-wanna)
2. Click **Fork** (top right)
3. You now have your own copy under your account

::: notes
Timing: 2 min
Ask who are familiar with GitHub workflows?
Explain that forking allows them to experiment without affecting the original repo.
:::

---

## Step 2: Make a Change

* Edit the `rutgers.txt` file
* Commit your changes with a meaningful message

::: notes
Timing: 3 min
Encourage small, safe changes to build confidence.
:::

---

## Step 3: Publish to Zenodo Sandbox

1. Log in to Zenodo sandbox
2. Activate the repository you forked
3. Create a GitHub release (tag your commit)
4. Zenodo generates a DOI for the release

::: notes
Timing: 5 min
Live demo, walk through it together.
Release title is concatenated with github repo for Zenodo title
Release notes become Zenodo description
:::

---

## Step 4: Make Additional Changes

* Update code or documentation
* Create a new release on GitHub
* Observe new DOI generated by Zenodo

::: notes
Timing: 3 min
Highlight that each release gets a unique DOI but all point back to the concept DOI.
This one they do on their own.
:::

---

## Step 5: Explore Examples

Look at successful uses of this mechanism:

![](assets/instrument.png){width=100 style="vertical-align: middle;"} _Instrument: [Low-Cost IoT Water Sampler](https://doi.org/10.5281/zenodo.10257622)_

![](assets/pipeline.png){width=100 style="vertical-align: middle;"} _Pipeline: [Tourmaline for eDNA analysis](https://doi.org/10.5281/zenodo.8144154)_

![](assets/analysis.png){width=100 style="vertical-align: middle;"} _Analysis: [Using H3 Grids for Biodiversity Indicators](https://doi.org/10.5281/zenodo.15113966)_

![](assets/documentation-svgrepo-com.png){width=100 style="vertical-align: middle;"} _Documentation: [Marine Data Mobilization Workshop](https://doi.org/10.5281/zenodo.7401979)_

::: notes
Timing: 3 min
Point out how each release has its own DOI, while the concept DOI points to all versions.
:::

---

## Step 6: Reflection

* Could you explain this to a collaborator?

::: notes
Timing: 5 min
Encourage participants to share experiences and ask clarifying questions. You will be asked to suggest and/or participate in mechanisms like this as a professional.
:::

---