Week-by-week checklist

A copyable timeline for getting to JOSS in about a month

This is the ambitious version of the journey — DOI + PyPI + Docker + JOSS in ~30 focused calendar days. Most people take longer. That’s fine. Use this as a template you can stretch to fit your actual schedule.

If you’re aiming for Level 0 only (DOI + citable archive, no PyPI or JOSS), stop after Week 1. If you’re aiming for Level 1 (installable + citable), stop after Week 2. Weeks 3-4 are Level 2 (JOSS paper).

---

Week 1 — Repo hygiene + Zenodo DOI (Level 0)

Goal: your code has a permanent DOI. Anyone can cite it.

• Day 1: Repo audit — is anything committed that shouldn’t be? Check git log for accidental credentials, private data, huge binaries. If yes, plan a git-filter-repo rewrite before going public.
• Day 1: Choose a licence, write LICENSE.
• Day 2: Rewrite README.md to answer the five questions (what, who, install, example, cite).
• Day 2: Write .gitignore covering secrets, data, checkpoints.
• Day 3: Write CITATION.cff with all authors’ ORCIDs.
• Day 3: Move code into a yourthing/ package directory if it isn’t already. Verify import yourthing works from the repo root.
• Day 4: Set up Zenodo → GitHub integration, sign in with GitHub, link ORCID.
• Day 4: Tag v0.1.0 → Create GitHub Release → Zenodo mints DOI.
• Day 5: Add DOI badge + concept DOI to README + CITATION.cff.
• Day 5: Post the DOI to your Slack / lab wiki / advisor. Verify strangers can cite you.

End of Week 1 deliverable: a public GitHub repo with a Zenodo DOI badge in the README.

---

Week 2 — pip install + Docker (Level 1)

Goal: a stranger can pip install yourthing or docker run your image, and it works.

• Day 6-7: Write pyproject.toml with dynamic = ["version"] + setuptools_scm. Split heavy dependencies into optional extras.
• Day 7: pip install -e . from a clean mamba env. Fix imports until it works.
• Day 8: Write MANIFEST.in. Run python -m build. Inspect the sdist and wheel. Trim as needed.
• Day 8: Reserve your PyPI name — add pending publisher on PyPI now, before someone else registers it.
• Day 9: Write .github/workflows/publish.yml with OIDC. Set up the pypi environment with required-reviewers.
• Day 9: TestPyPI first — verify the workflow end to end. Then real PyPI.
• Day 10: Write Dockerfile. Build locally. Test that docker run produces a working JupyterLab.
• Day 10: Write .github/workflows/docker.yml. Push a tag → verify GHCR gets the image.
• Day 11: Change GHCR image visibility to public. (Do not forget this step. Almost everyone forgets this step.)
• Day 12: pip install yourthing and docker pull ghcr.io/... from a different machine. Verify both work.
• Day 12: Add pip + Docker install instructions to README.

End of Week 2 deliverable: pip install yourthing works for strangers. GHCR image is public.

---

Week 3 — Tests + CI + docs (Level 2 prep)

Goal: green tests badge, real test coverage, JOSS-ready documentation.

• Day 13: Add pytest + pytest-cov to dev extras. Write a smoke-test tests/test_smoke.py.
• Day 14-15: Write tests for every public function that appears in your README example. Aim for ≥ 50% coverage.
• Day 15: .github/workflows/tests.yml matrix (2 OS × 3 Python versions). Get it green.
• Day 16: Add tests badge + coverage badge to README.
• Day 17: Write CONTRIBUTING.md. Copy-paste from geoai-datacubes or another well-set-up JOSS repo.
• Day 17: Write CODE_OF_CONDUCT.md. Use Contributor Covenant v2.1.
• Day 18: Add CHANGELOG.md if you don’t have one. Backfill for v0.1.0.
• Day 19: Sweep all docs for stale references, broken links, out-of-date screenshots. This one is boring but is the item that catches reviewers.

End of Week 3 deliverable: repo has all the community-guidelines pieces. Tests + coverage badges are green.

---

Week 4 — paper.md + submit (Level 2)

Goal: JOSS paper drafted, PDF renders cleanly, form submitted.

• Day 20: Draft paper.md — Summary + Statement of need. Aim for 500-700 words at this stage.
• Day 21: Draft the Relationship to related tooling section. Cite competing packages.
• Day 22: Draft Research applications. Cite every paper that already uses your software — this is the strongest evidence of research use under JOSS’s Jan 2026 criteria.
• Day 22: Write the Acknowledgements + AI disclosure per Chapter 5.
• Day 23: Build paper.bib with entries for every citation. Verify no dangling citations, no uncited entries.
• Day 23: Set up .github/workflows/draft-pdf.yml. Verify it produces a rendered PDF as a workflow artifact.
• Day 24: Review the rendered PDF. Fix Unicode-glyph issues (≈ → $\approx$), trim to ≤ 1000 words.
• Day 25: Circulate the PDF to co-authors for review. Give them 2-3 days.
• Day 27: Incorporate co-author feedback. Re-render.
• Day 28: Get all co-author ORCIDs. Update CITATION.cff and paper.md front matter.
• Day 29: Final pre-flight check against the submission checklist.
• Day 30: Submit at https://joss.theoj.org/papers/new.

End of Week 4 deliverable: JOSS submission acknowledged, in the review queue.

---

What happens next (Weeks 5-20-ish)

Not your daily work anymore, but plan for:

• Weeks 5-8: Editorial pre-check + reviewer assignment.
• Weeks 8-16: Active review on a GitHub issue in openjournals/joss-reviews. Reviewers file checklist items; you iterate.
• Weeks 16-20: Acceptance + JOSS DOI + your paper appears in Google Scholar within a couple of weeks of publication.

Total elapsed time from submission to publication: usually 2-6 months, dominated by the reviewer-assignment step.

---

If you’re behind schedule

The schedule above assumes ~2 hours a day of focused work. Realistic slippage:

• If you don’t already have a package structure, add a week for the notebook → package refactor.
• If your tests are non-trivial (network I/O, expensive fits, mixed OS behaviour), add a week.
• If your co-authors are in three time zones, expect the review round-trips in Week 4 to slip a week or more.

The most common slippage: discovering during Week 2 that your pyproject.toml doesn’t quite work on someone else’s machine because of a hidden native-library dependency, and spending 4 days debugging install paths. Budget for this by doing Week 2’s cross-machine install test as early as possible.

---

The 30-day version, ultra-compressed

If you truly want to submit in 30 calendar days and you already have working code:

• Days 1-3: Level 0 (repo hygiene + Zenodo DOI).
• Days 4-10: Level 1 (pyproject + PyPI + Docker + CI).
• Days 11-20: Tests + community-guidelines + docs.
• Days 21-28: Draft + circulate + polish paper.md.
• Days 29-30: Submit.

This assumes you don’t have to refactor your code structure. If you’re starting from “a folder of scripts I’ve been running for two years,” double every estimate.