BuckAI Open-Source Handbook

Turn your research code into a citable, installable, peer-reviewed open-source package. Zenodo DOI in 30 minutes, PyPI + Docker in a couple of days, a JOSS paper in a few weeks. A practical, opinionated walk-through from the BuckAI Observatory.

👋 Not sure if this applies to you?

Start with Why bother? — a plain-English explanation of what you get out of publishing your research code, structured as three levels of increasing effort and reward. Level 0 (Zenodo DOI) is a 30-minute investment that turns your code into a citable, Google-Scholar-indexed artifact. Levels 1 and 2 are optional and layered on top.

What this handbook is

A practical, opinionated walk-through for turning working research code into a citable, installable, peer-reviewed open-source package. Written by the BuckAI Observatory at Ohio State University for its students, postdocs, and collaborators — but useful for anyone with a research script they’d like to see out in the world.

It takes you from “my code works on my laptop and I paste it into emails when someone asks” to “my code is pip install-able, has a DOI I can cite, runs in a public Docker container, and has a peer-reviewed paper attached to it in Google Scholar.”

The handbook is opinionated about workflows that work in practice, and warns about the ones that look fine but cost you a week when they break (accidentally committing credentials, name-squatting on PyPI, Co-Authored-By trailers you can’t easily undo, etc.).

Browse by topic

Level 0 — Citable

Give your code a permanent DOI so people can cite it in papers, grant applications, and CVs — even a decade from now, even if the repo moves.

Why bother? — the three-levels pitch
Repo hygiene — LICENSE, README, tests folder
Zenodo DOI — 30-minute wiring, concept vs version DOIs

Level 1 — Installable

Let a stranger pip install yourthing and reproduce your results — without cloning your repo, without emailing you for help.

Make it pip-installable — pyproject.toml + setuptools_scm
PyPI Trusted Publishing — OIDC, no API tokens
Tests + CI — the minimum viable pytest matrix
Docker / GHCR — a one-command reproduction environment

Level 2 — Peer-reviewed

A JOSS publication is indexed by Google Scholar, gets a Crossref-registered DOI and citation string, and appears on your CV like any other peer-reviewed paper.

paper.md + paper.bib — the JOSS format explained
JOSS submission walk-through — the online form, field by field

Special topics

Data not fully open?

Your training data is under a licence, embargoed, or genuinely private (medical records, commercial LIDAR, restricted satellite imagery)?

When your data isn’t fully open — three practical strategies with worked examples.

Using AI assistants

Claude Code, GitHub Copilot, or ChatGPT wrote a lot of your codebase. Is that a problem for JOSS? What do you need to disclose?

AI-assisted development, safely — usage patterns, JOSS disclosure requirements, what to keep out of git history.

Week-by-week checklist

A copyable timeline for the ambitious version of this journey — DOI, PyPI, Docker, JOSS all within a month.

Checklist + timeline — the ordered list of concrete steps.

Appendices

Anatomy of a well-set-up repo — a walk-through of geoai-datacubes, the BuckAI reference implementation, with links to the actual files you’d copy patterns from.
Common pitfalls — the mistakes that cost the most time to undo: accidentally committing an API key, choosing a PyPI name someone will fight you for, GitHub’s Contributors-widget cache, and others.

About this handbook

Built by the BuckAI Observatory at The Ohio State University. Companion resources:

🖥️ BuckAI HPC Handbook — using OSU’s Unity HPC cluster.
🛰️ geoai-datacubes — the reference implementation this handbook draws its examples from.

Suggestions, corrections, and pull requests are welcome — file an issue in the handbook repo.