Why bother? The three levels of open-source publishing
Why bother?
Most research code lives on a lab hard drive or in a private GitHub repo, cited — if it’s cited at all — as “code available on request.” That’s a shame. A modest investment turns that code into a citable, discoverable, install-in-one-command research artifact, and the returns on that investment compound: it raises your paper’s citation count, it makes collaboration easier, it lets a future version of you find your own work three years from now, and it counts as a peer-reviewed publication on your CV if you go far enough.
This handbook walks through three levels of increasing effort and reward. Pick whichever level fits your project’s stage — each level is a complete stopping point. You do not have to do all three.
Level 0 — Zenodo DOI (about 30 minutes)
Once your repo is on GitHub with a README.md and a LICENSE, you can wire it to Zenodo. Every subsequent GitHub Release then automatically archives your repo and mints two DOIs:
- A concept DOI that always points to “the latest version” — this is what you cite generically (“we used
yourthing[@yourthing_concept_doi]”). - A version DOI per release — this is what you pin from a paper for exact reproducibility (“we used
yourthingv0.3.1 [@yourthing_v0_3_1]”).
Zenodo is indexed by Google Scholar, so your code shows up in citation searches next to conventional papers.
Effort: an afternoon. Reward: your code is permanently citable. A paper that references it will have a working link a decade from now, even if the repo moves. This is the single highest-return step in this handbook.
If you’re a MSc student, or a PhD student whose software is a small piece of a bigger research story, Level 0 is often all you should do. Levels 1 and 2 add real value only when other people are likely to try to run your code.
Level 1 — pip install + Docker (one to two days)
Adding a pyproject.toml makes your code installable via pip install yourthing. Publishing to PyPI — using OIDC “Trusted Publishing” so you never have to manage an API token — lets strangers install it without cloning your repo or reading your README. A parallel Docker image on GitHub Container Registry (GHCR) means a reader can spin up your full stack — Python, dependencies, GPU environment, notebooks — in one command:
pip install yourthing
# or
docker run -p 8888:8888 ghcr.io/yourorg/yourthing:latestYour citation count goes up at Level 1 because it’s actually easy for someone to try your code before citing it. The friction of “clone this, set up a Python 3.11 env, install these unpinned dependencies, hope it works on your OS” is enough to lose most would-be users. pip install and docker run remove that friction.
Effort: one to two focused days if you already have a working script; longer if you first need to break a Jupyter notebook into a proper package structure. Reward: meaningful adoption. Your work reaches people who would never have cloned your repo.
Level 2 — JOSS paper (two to four weeks)
The Journal of Open Source Software (JOSS) is a peer-reviewed venue that publishes short papers about research software. The “paper” is a ~1000-word Markdown file explaining what the software does and why it exists; the actual review is a code review, on GitHub, in the open, with named reviewers.
A JOSS publication is:
- Indexed by Google Scholar — so it counts in citation counters and shows up next to conventional papers in citation searches. JOSS is not currently indexed by Scopus or Web of Science; if your institution counts publications only through those databases, factor that in.
- Given a Crossref-registered DOI and citation string — formatted like a normal journal paper.
- Peer-reviewed — appears on your CV like any other peer-reviewed publication.
JOSS reviewers evaluate three things: (1) does the software solve a real research problem well, (2) is it usable by someone who is not the author, and (3) is the paper itself readable and honest about scope and limitations. The scope-and-significance bar was recently updated (January 2026) to emphasise research impact and open-source software practices over old proxies for effort like lines of code — meaning AI-assisted development is explicitly welcome, provided you disclose it and the software genuinely serves the research community.
Effort: two to four weeks part-time, most of it in polishing docs and writing paper.md. The code itself is usually already there. Reward: a citable, peer-reviewed publication for the code you already wrote, without doing a whole new project. Cite it on grants and tenure files.
You almost certainly used an AI coding assistant to help build your code. That’s fine — JOSS’s updated policy explicitly does not require the human-written code to be a certain percentage. What it does require is that the software show human intellectual contribution — problem framing, key design decisions, sustained development, and open-source practices (tests, documentation, licensing, versioned releases, transparent issue tracking). The paper.md is your chance to make that human contribution visible.
How to decide which level to aim for
MSc project or a one-off analysis
Aim for Level 0. A DOI + README + LICENSE is enough for the code to be permanently linkable from your thesis, your first-author paper, and your CV.
Do not spend a week making it pip install-able if nobody is going to install it.
PhD student’s core software artifact
Aim for Levels 0 + 1. If your code is the tool other people in your subfield are going to want to try, pip install is the difference between 5 citations and 50.
Consider Level 2 if your PhD is centred on the software itself.
Lab-wide, multi-year pipeline
Aim for all three levels. geoai-datacubes is the BuckAI example: 26 satellite missions, four data providers, ~90 tests, Docker image, JOSS submission. This handbook was written from that project’s experience.
What comes next
Start with Step 1 — Repo hygiene. Even if you decide to stop at Level 0, most of the value is in getting the repo into a state where a stranger can understand it in ten minutes.