Step 8 — JOSS submission walk-through

Submitting to JOSS: the form, field by field

Your paper is written. Your Docker image is public. Your PyPI release is live. Your DOI is minted. You are ready to submit.

JOSS submission happens at https://joss.theoj.org/papers/new. The form is short — under 10 fields — but a couple of them are worth thinking about carefully before you paste anything in.

This chapter walks through every field, with the answers you should have prepared.

Before you open the form: a pre-flight check

If any of these is missing, go back and finish it first. Reviewers will bounce a submission for missing pieces.

Field-by-field walk-through

“Repository URL”

The HTTPS URL of your GitHub repo:

https://github.com/yourorg/yourthing

Not the SSH URL. Not the URL of your Zenodo record. Not your personal fork.

“Name of git branch containing the paper, not the path”

Leave blank if paper.md is on the default branch (usually main). Only fill this in if the paper lives on some other branch (rare — don’t do this).

“Version”

The version of your software that the paper describes. This is the git tag on the release you want reviewed:

0.1.0

Note: no v prefix. 0.1.0, not v0.1.0.

“Software archive DOI”

Your Zenodo version DOI for the release that matches the “Version” field above. The full DOI, not the URL:

10.5281/zenodo.1234567

Not the concept DOI — the version DOI.

“Main subject of the paper”

A subject-area classification for editor routing. Pick the one that best matches the domain your software serves, not the language it’s written in:

  • Earth observation / satellite / geospatial → Earth, Environmental, and Space Sciences
  • Physics / astronomy → Astronomical Sciences or Physical Sciences
  • Bioinformatics / systems biology → Biological Sciences
  • Health, clinical, epi → Health Sciences
  • Pure ML / stats without a specific domain → Computer Sciences, Information and General Works

If the form offers a secondary/keywords field, add “Machine Learning” or “Data Science” or “Geospatial” as tags.

“Has any portion of the submitted work been published or submitted, or is planned for submission, to another peer-reviewed publication venue?”

A single free-text field that also asks you to describe the software briefly and disclose conflicts of interest. Answer three things:

  1. Prior/parallel submissions of the paper itself. For a first-time JOSS submission this is “No portion of this paper has been previously published, submitted, or is planned for submission to another peer-reviewed venue. This is a first JOSS submission — not a resubmission and not a second paper about this software.”
  2. A one-to-two-line description of the software. Copy from your paper’s Summary or README.
  3. Papers that use the software (research applications). Cite any you’ve cited in paper.md’s “Research applications” section. These are downstream applications, not overlapping software papers, but reviewers appreciate you saying so explicitly.
  4. Conflicts of interest. Financial, advisory, consulting, equity, IP-license — anything a reviewer might want to know. If none, say so.

A template you can adapt:

No portion of this paper has been previously published, submitted, or is planned
for submission to another peer-reviewed venue. This is a first JOSS submission
— not a resubmission and not a second paper about this software.

The software: yourthing is an open-source Python pipeline that [what it does,
in one or two sentences].

The library has been used in research papers by [authors and collaborators],
cited in the manuscript's "Research applications" section as evidence of
research use — [paper 1], [paper 2]. These are downstream applications, not
overlapping software papers.

Conflicts of interest: none. Development was supported by [funding sources]
as already acknowledged in the paper. There is no financial, advisory, or
consulting relationship with any data provider, vendor, or interested party
referenced in the manuscript.

“Preferred editor” (optional)

If you have a specific editor in mind (someone whose area matches your paper), you can name them. Otherwise leave blank — JOSS’s editorial team routes based on the subject-area classification.

“Preferred reviewers”

Same idea for reviewers. If you know people who would be qualified (and don’t have a conflict of interest with you — no former advisors, no current collaborators, no lab-mates), you can suggest them. JOSS is more receptive to reviewer suggestions than most journals because their reviewer pool is smaller.

The form usually asks for two suggestions. Leave blank if you don’t know anyone appropriate.

What happens after you click submit

  1. Editorial pre-check (~1 week). An editor checks that the submission is in scope, that the repo has the required pieces, and that paper.md renders. If anything obvious is missing, they’ll ask you to fix it before opening review.
  2. Reviewer assignment (~2-6 weeks). Two reviewers are assigned. This is often the longest wait, because JOSS’s reviewer pool is finite and every submission needs domain-matched reviewers.
  3. Review (~4-12 weeks). Reviewers file a checklist on a GitHub issue in the openjournals/joss-reviews repo — you’ll be @-mentioned. Each item is either checked, or comes with a specific request. You iterate on the paper and the code until every box is ticked.
  4. Acceptance and publication (~1 week after last check). Once both reviewers sign off, the editor recommends acceptance. JOSS assigns a DOI to the paper (this is different from your Zenodo software DOI — one is for the paper, one is for the archived code).

Total: from submission to acceptance is usually 2-6 months, dominated by the reviewer-assignment step.

During review: what to expect

Reviewers focus on:

  • Installation. Can they actually get your software installed from scratch on their own machine?
  • Documentation. Is the README clear? Does the example in the README work?
  • Tests. Do they run? Do they cover the important parts?
  • Statement of need. Is it convincing? Is there prior work you should have cited?
  • Community guidelines. Do you have a CONTRIBUTING.md? A CODE_OF_CONDUCT.md? A clear path for reporting bugs?

They usually don’t focus on:

  • Line-by-line code review of your algorithms.
  • Whether they’d have designed it the same way.
  • Novelty of the science. (JOSS is about software craftsmanship, not scientific novelty. The novelty is presumed to be in the papers using the software.)

The tone is generally collaborative rather than adversarial — JOSS reviewers are usually researchers who’ve been in your shoes.

Common revision requests

  • “Add a CONTRIBUTING.md.” — Standard. See the CONTRIBUTING.md in geoai-datacubes for a template.
  • “Add a CODE_OF_CONDUCT.md.” — Standard. The Contributor Covenant v2.1 is the default choice.
  • “Test coverage is thin in module X.” — Add tests. See Step 5.
  • “Your Statement of need doesn’t explain how you differ from sortof_related_package.” — Add a sentence to paper.md addressing it. Cite the other package.
  • “The Docker image is private.” — Change visibility to public.
  • “I can’t install this without CUDA.” — Add a CPU-only install path to your README.

After acceptance: the DOI + citation

The published paper is at https://doi.org/10.21105/joss.NNNNN. JOSS also renders a per-paper landing page at https://joss.theoj.org/papers/10.21105/joss.NNNNN.

Update:

  • The DOI badge in your README (JOSS gives you the Markdown snippet).
  • Your CITATION.cff — add a preferred-citation: block pointing at the JOSS paper.
  • Your CV. This paper counts.

Congratulations. You’re done.

Checklist for the submission form itself

Now go to https://joss.theoj.org/papers/new and paste. Then go make coffee — the reply from JOSS’s editor-in-chief usually lands within an hour or two, confirming your submission was received.