- A readiness matrix with actual evidence links.
- Scientific tests, installation docs and a versioned release.
- A paper draft and policy-aligned contribution/AI statements.
Separate the software from its paper
A short paper cannot repair an inadequate software project. Define the research problem, users, inputs, outputs and concrete difference from existing tools first.
Current JOSS guidance addresses at least six months of active public development; suddenly uploading an older private project is not the same history. Demonstrate actual research use and maturity, and recheck submission requirements when applying.
Build an assessable readiness record
Provide a suitable licence, installation instructions, quick start, repeatable example, automated tests, contribution guidance and an issue route. Do not assume a small classroom script or minor single-purpose utility qualifies.
Record evidence links and status. “Has tests” is vague: identify the input/output contract or scientific error each test checks. A green CI badge alone does not prove methodological validity.
Scientific rather than cosmetic tests
Teaching example: the mean of [2,4,6] must be 4, and empty input must be explicitly rejected. For regression, use synthetic data with a known coefficient and an independent comparison; repeating the implementation inside its test gives weak evidence.
Cover boundaries, missingness, units and version changes. Explain when invalid output is prevented. This site’s downloadable mini-project is educational and is not presented as JOSS-eligible software.
Paper, citation and version
Describe the problem, users, related software, design and research need with real references. Version the code release and explain how to cite that specific version; disclose dates and dependencies.
State author contributions and future maintenance. Provide evidence of actual scientific use; repository stars or downloads alone do not establish validated research use.
AI use and review communication
Current JOSS policy requires disclosure of AI tools, versions, scope and human review in software development. Also read its restrictions on AI-generated conversational responses to editors or reviewers; the translation exception is distinct.
Authors must explain and correct logic, licensing, security and behaviour. Executability alone does not establish trustworthiness. Retain human review and meaningful testing.
Completed teaching worksheet
This is a hypothetical teaching case, not observed data, an actual review or a publication acceptance. Numbers illustrate decisions.
| Decision or record | Teaching example | Your project action |
|---|---|---|
| Need | A tool for a defined scientific task | Explain users and alternatives. |
| History | Teaching demo lacks JOSS history | Link actual development evidence. |
| Tests | Known-answer mean and regression cases | List contracts and error checks. |
| Docs | Install, example, licence and contributions | Verify from a clean environment. |
| Disclosure | Assistance and human review | Apply the actual outlet policy. |
Deliverables and completion checks
- A readiness matrix with actual evidence links.
- Scientific tests, installation docs and a versioned release.
- A paper draft and policy-aligned contribution/AI statements.
Version and scope references: JOSS — Submission requirements and AI policy · Cornell Data Services — Writing READMEs for Research Data
Sources and further reading
Official sources for verification and further reading