Skip to content

JOSS manuscript preparation

The manuscript is paper/paper.md, with references in paper/paper.bib and software citation metadata in CITATION.cff. The JOSS Paper workflow validates these files and builds an official JOSS draft PDF on relevant pull requests.

Validate the manuscript

From the repository root, in a Python environment:

python -m pip install -r paper/requirements.txt
python paper/check.py
cffconvert --validate

The checker verifies section coverage, word count, citation keys, ORCID checksums, matching title and author identifiers, and unfinished author markers. For the final reference audit, also run:

python paper/check.py --check-dois

This requires curl and network access. It checks DOI resolution and compares bibliographic titles, volumes, issues, and pages with Crossref. A resolving DOI can still point to the wrong article. Author lists, attribution, and references without DOIs also need human review.

Build the official proof

Download the paper artifact from the JOSS Paper workflow, or build locally with Inara and Docker:

docker run --rm --volume "$PWD/paper:/data" \
  --user "$(id -u):$(id -g)" --env JOURNAL=joss openjournals/inara

Inspect paper/paper.pdf, including every reference page. The draft watermark and placeholder DOI, publication details, and submission date are supplied by the journal template and are replaced during the publication process.

Check the supporting materials

Run the software checks, the GBT reference workflow, and the RM-synthesis reference example. The Reference Workflows action checks the GBT measurements and portable replay on Linux, using both the published package and the current checkout with pinned dependencies. The example data remain a separate downloadable release asset; the reference snapshot and expected results are in docs/examples/.

Before submission, the authors should review the final proof and agree on authorship, affiliations, contribution credit, funding acknowledgements, conflicts of interest, and the AI disclosure. Confirm that its statements about human review and scientific decisions accurately describe the work. The disclosure names the known assistants and explicitly records the absence of a systematic historical model/version record; it does not invent missing details. Record identifiable models and versions for subsequent assistance, and add any historical details that can be recovered reliably before submission.

The submission form should identify any related science or methods papers, including manuscripts in preparation or under review. Retain factual evidence of the research uses described in the paper, such as a project report or analysis record, in case the editors request it. Confirm credit for any additional contributors before submission.

Reproducibility claims

Distinguish preservation of stored results from repeating calculations. The current session JSON records its schema version, source checksum, settings, available results, and software provenance. Each computation has its own software identity so reopening or partial recomputation cannot relabel an old fit with a new environment. Exports retain this record, including a sidecar for SIGPROC windows. Missing historical provenance remains unknown. See Exports and Snapshots for the preservation procedure, source-identity limitations, and replay scope.

tests/test_historical_compatibility.py reads fixtures generated by five actual releases; tests/fixtures/compatibility/README.md documents the exact coverage and the intentional 0.2.0 uncertainty differences. Do not turn a known change in scientific semantics into a claimed guarantee of identical recalculation.

Submission and the final archive

Follow the current JOSS submission requirements and paper guidance. The manuscript and software must be available together in the public repository; a submission branch is allowed. Use the branch containing the final reviewed manuscript if it has not yet been merged.

Check the current screening rules as well as manuscript formatting: JOSS requires more than six months of public development with sustained iteration and evidence of actual research use. Old local commit dates alone do not establish when a repository became public. Retain evidence of the relevant public releases, issues, reviews, and research applications.

After review, archive the exact final tagged software release with Zenodo or figshare and provide its version and archival DOI. A final archive DOI is not required for the initial submission. Preserve the example data, provenance, and sharing terms in a suitable archive as well; a GitHub release asset alone does not establish that a separate archival deposit exists.

arXiv timing

The JOSS preprint policy allows preprints before, during, or after review. There is no need to wait for JOSS publication. A practical sequence is to finish the technical claims and coauthor review, submit to JOSS, and post the agreed manuscript to arXiv around the same time. Describe its status accurately; do not label it accepted before acceptance. After publication, add the JOSS DOI and journal reference and upload a revised version if the text changed during review.

Build the clean preprint and upload archive from the same Markdown manuscript:

docker pull openjournals/inara@sha256:a0414b8b72fd8923917ede614d340d98dc7aa3102aabc2e955e9c02a6100fd62
python paper/build_arxiv.py

The builder writes output/arxiv/flits-arxiv-source.zip, flits-arxiv.pdf, main.tex, and build-report.json. It checks the bibliography and compiles the exact extracted upload with pdfLaTeX in an isolated container with networking disabled. References are embedded in main.tex; no external bibliography, journal class, or JOSS review watermark is needed at arXiv. Upload the ZIP and select pdfLaTeX. Inspect arXiv's own generated preview before finalizing; local validation cannot substitute for their server-side checks. The report records input/output checksums so a stale preprint can be detected.