The Journal of Open Source Software

The Journal of Open Source Software (JOSS) is a developer friendly journal for research software packages.

What exactly do you mean by 'journal'

The Journal of Open Source Software (JOSS) is an academic journal (ISSN 2475-9066) with a formal peer review process that is designed to improve the quality of the software submitted. Upon acceptance into JOSS, a CrossRef DOI is minted and we list your paper on the JOSS website.

Don't we have enough journals already?

Perhaps, and in a perfect world we'd rather papers about software weren't necessary but we recognize that for most researchers, papers and not software are the currency of academic research and that citations are required for a good career.

We built this journal because we believe that after you've done the hard work of writing great software, it shouldn't take weeks and months to write a paper about your work.

You said developer friendly, what do you mean?

We have a simple submission workflow and extensive documentation to help you prepare your submission. If your software is already well documented then paper preparation should take no more than an hour.

You can read more about our motivations to build JOSS in our announcement blog post

Code of Conduct

Although spaces may feel informal at times, we want to remind authors and reviewers (and anyone else) that this is a professional space. As such, the JOSS community adheres to a code of conduct adapted from the Contributor Covenant code of conduct.

Authors and reviewers will be required to confirm they have read our code of conduct, and are expected to adhere to it in all JOSS spaces and associated interactions.

Open Source Initiative

Osi small

JOSS is a proud affiliate of the Open Source Initiative. As such we are committed to public support for open source software and the role OSI plays therein. You can read more about the OSI's affilate program here.



The Journal of Open Source Software is a NumFOCUS-sponsored project.

Author Guidelines

If you've already licensed your code and have good documentation then we expect that it should take less than an hour to prepare and submit your paper to JOSS.

What does a typical submission flow look like?

Before you submit we need you to:

  • Make software available in an open repository (GitHub, Bitbucket etc.) and include an OSI approved open source license
  • Author a short Markdown paper with a title, summary, author names, affiliations, and key references. See an example here
  • Ideally we would also like you to create a metadata file and include it in your repository describing your software. This script automates the generation of this metadata.

What should my paper contain?

JOSS welcomes submissions from broadly diverse research areas. For this reason, we request that authors include in the paper some sentences that would explain the software functionality and domain of use to a non-specialist reader. Your submission should probably be somewhere between 250-1000 words.

  • A list of the authors of the software and their affiliations
  • A summary describing the high-level functionality and purpose of the software for a diverse, non-specialist audience
  • A clear statement of need that illustrates the purpose of the software
  • A list of key references including a link to the software archive
  • Mentions (if applicable) of any ongoing research projects using the software or recent scholarly publications enabled by it

As this list shows JOSS papers are only permitted to contain a limited set of metadata (see header below), Summary & Reference sections. You can see an example paper here. Given this paper format it is not permitted to write a "full length" paper i.e. one that includes software documentation such as API (Application Programming Interface) functionality, as this should instead be outlined in the software documentation.

  Example adapted from "Gala: A Python package for galactic dynamics",
  Adrian M. Price-Whelan,
title: 'Gala: A Python package for galactic dynamics'
  - Python
  - astronomy
  - dynamics
  - galactic dynamics
  - milky way
  - name: Adrian M. Price-Whelan
    orcid: 0000-0003-0872-7098
    affiliation: "1, 2" # (Multiple affiliations must be quoted)
  - name: Author 2
    orcid: 0000-0000-0000-0000
    affiliation: 2
 - name: Lyman Spitzer, Jr. Fellow, Princeton University
   index: 1
 - name: Institution 2
   index: 2
date: 13 August 2017
bibliography: paper.bib

# Summary

The forces on stars, galaxies, and dark matter under external gravitational
fields lead to the dynamical evolution of structures in the universe. The orbits
of these bodies are therefore key to understanding the formation, history, and
future state of galaxies. The field of "galactic dynamics," which aims to model
the gravitating components of galaxies to study their structure and evolution,
is now well-established, commonly taught, and frequently used in astronomy.
Aside from toy problems and demonstrations, the majority of problems require
efficient numerical tools, many of which require the same base code (e.g., for
performing numerical orbit integration).

``Gala`` is an Astropy-affiliated Python package for galactic dynamics. Python
enables wrapping low-level languages (e.g., C) for speed without losing
flexibility or ease-of-use in the user-interface. The API for ``Gala`` was
designed to provide a class-based and user-friendly interface to fast (C or
Cython-optimized) implementations of common operations such as gravitational
potential and force evaluation, orbit integration, dynamical transformations,
and chaos indicators for nonlinear dynamics. ``Gala`` also relies heavily on and
interfaces well with the implementations of physical units and astronomical
coordinate systems in the ``Astropy`` package [@astropy] (``astropy.units`` and

``Gala`` was designed to be used by both astronomical researchers and by
students in courses on gravitational dynamics or astronomy. It has already been
used in a number of scientific publications [@Pearson:2017] and has also been
used in graduate courses on Galactic dynamics to, e.g., provide interactive
visualizations of textbook material [@Binney:2008]. The combination of speed,
design, and support for Astropy functionality in ``Gala`` will enable exciting
scientific explorations of forthcoming data releases from the *Gaia* mission
[@gaia] by students and experts alike. The source code for ``Gala`` has been
archived to Zenodo with the linked DOI: [@zenodo]

Citations to entries in paper.bib should be in

Figures can be included like this: ![Example figure.](figure.png)

# Acknowledgements

We acknowledge contributions from Brigitta Sipocz, Syrtis Major, and Semyeong
Oh, and support from Kathryn Johnston during the genesis of this project.

# References
  Example paper.bib:
  	Adsnote = {Provided by the SAO/NASA Astrophysics Data System},
  	Adsurl = {},
  	Archiveprefix = {arXiv},
  	Author = {{Pearson}, S. and {Price-Whelan}, A.~M. and {Johnston}, K.~V.},
  	Eprint = {1703.04627},
  	Journal = {ArXiv e-prints},
  	Keywords = {Astrophysics - Astrophysics of Galaxies},
  	Month = mar,
  	Title = {{Gaps in Globular Cluster Streams: Pal 5 and the Galactic Bar}},
  	Year = 2017}

  	Adsnote = {Provided by the SAO/NASA Astrophysics Data System},
  	Adsurl = {},
  	Author = {{Binney}, J. and {Tremaine}, S.},
  	Booktitle = {Galactic Dynamics: Second Edition, by James Binney
      and Scott Tremaine.~ISBN 978-0-691-13026-2 (HB).~Published by
      Princeton University Press, Princeton, NJ USA, 2008.},
  	Publisher = {Princeton University Press},
  	Title = {{Galactic Dynamics: Second Edition}},
  	Year = 2008}

  	Abstractnote = {

Gala is a Python package for Galactic astronomy and gravitational dynamics. The bulk of the package centers around implementations of gravitational potentials, numerical integration, and nonlinear dynamics.

}, Author = {Adrian Price-Whelan and Brigitta Sipocz and Syrtis Major and Semyeong Oh}, Date-Modified = {2017-08-13 14:14:18 +0000}, Doi = {10.5281/zenodo.833339}, Month = {Jul}, Publisher = {Zenodo}, Title = {adrn/gala: v0.2.1}, Year = {2017}, Bdsk-Url-1 = {}} @article{gaia, author = {{Gaia Collaboration}}, title = "{The Gaia mission}", journal = {\aap}, archivePrefix = "arXiv", eprint = {1609.04153}, primaryClass = "astro-ph.IM", keywords = {space vehicles: instruments, Galaxy: structure, astrometry, parallaxes, proper motions, telescopes}, year = 2016, month = nov, volume = 595, doi = {10.1051/0004-6361/201629272}, adsurl = {}, } @article{astropy, author = {{Astropy Collaboration}}, title = "{Astropy: A community Python package for astronomy}", journal = {\aap}, archivePrefix = "arXiv", eprint = {1307.6212}, primaryClass = "astro-ph.IM", keywords = {methods: data analysis, methods: miscellaneous, virtual observatory tools}, year = 2013, month = oct, volume = 558, doi = {10.1051/0004-6361/201322068}, adsurl = {} }

Submission then is as simple as:

What are your requirements for submission?

  • Your software should be open source as per the OSI definition
  • Your software should have an obvious research application
  • You should be a major contributor to the software you are submitting
  • Should be a significant contribution to the available open source software that either enables some new research challenges to be addressed or makes addressing research challenges significantly better (e.g., faster, easier, simpler)
  • Should be feature complete (no half-baked solutions)
  • Minor, 'utility' packages, including 'thin' API clients are not acceptable

In addition, the software associated with your submission must:

  • Be stored in a repository that can be cloned without registration
  • Be stored in a repository that is browsable online without registration
  • Have an issue tracker that is readable without registration
  • Permit individuals to create issues/file tickets against your repository

JOSS publishes articles about research software. This definition includes software that: solves complex modeling problems in a scientific context (physics, mathematics, biology, medicine, social science, neuroscience, engineering); supports the functioning of research instruments or the execution of research experiments; extracts knowledge from large data sets; offers a mathematical library, or similar.

What about submissions that rely upon proprietary languages/development environments?

We strongly prefer software that doesn't rely upon proprietary (paid for) development environments/programming languages. However, provided your submission meets our submission requirements (including having a valid open source license) then we will consider your submission for review. Should your submission be accepted for review, we may ask you, the submitting author, to help us find reviewers who already have the required development environment installed.

If you think your submission is not an obvious fit or have a question then please submit a pre-submission enquiry

What does a typical review process look like?

We encourage you to familiarize yourself with our reviewer guidelines as this will help you understand what our reviewers will be looking for. Broadly speaking though, provided you have followed our pre-submission steps and meet our submission requirements then you should expect a rapid review (typically less than two weeks).

After submission:

  • One or more JOSS reviewers are assigned and the review is carried out in the reviews repository
  • Authors respond to reviewer-raised issues (if any are raised) on the submitted repository's issue tracker. Reviewer contributions, like any other contributions, should be acknowledged in the repository.
  • Upon successful completion of the review, deposit a copy of your (updated) repository with a data-archiving service such as Zenodo or figshare, issue a DOI for the archive, and update the review issue thread with your DOI.
  • After assignment of a DOI, your paper metadata is deposited in CrossRef and listed on the JOSS website.
  • And that's it.

Reviewer Guidelines

Firstly, thank you so much for agreeing to review for the Journal of Open Source Software (JOSS), we're delighted to have your help. This document is designed to outline our editorial guidelines and help you understand our requirements for accepting a submission into the JOSS. Our review process is based on a tried-and-tested approach of the rOpenSci collaboration.

Some guiding principles for you the reviewer

We like to think of JOSS as a 'developer friendly' journal. That is, if the submitting authors have followed best practices (have documentation, tests, continuous integration, and a license) then their review should be extremely rapid.

For those authors that don't quite meet the bar, please try to give clear feedback on how they could improve their submission. A key goal of JOSS is to raise the quality of research software generally and you (the experienced reviewer) are well placed to give this feedback.

We encourage reviewers to file issues against the submitted repository's issue tracker. Include in your review links to any new issues that you the reviewer believe to be impeding the acceptance of the repository. (If the submitted repository is a GitHub repository, mentioning the review issue URL in the submitted repository's issue tracker will create a mention in the review issue's history.)

The JOSS paper

The JOSS paper (the PDF associated with this submission) should only include:

  • A list of the authors of the software
  • Author affiliations
  • A short summary describing the high-level functionality of the software
  • A list of key references including a link to the software archive

Note the paper should not include software documentation such as API (Application Programming Interface) functionality, as this should be outlined in the software documentation.

Software license

There should be an OSI approved license included in the repository. Common licenses such as those listed on are preferred. Note there should be an actual license file present in the repository not just a reference to the license.

Acceptable: A plain-text LICENSE file with the contents of an OSI approved license
Not acceptable: A phrase such as 'MIT license' in a README file


There should be sufficient documentation for you, the reviewer to understand the core functionality of the software under review. A high-level overview of this documentation should be included in a README file (or equivalent). There should be:

A statement of need

The authors should clearly state what problems the software is designed to solve and who the target audience is.

Installation instructions

There should be a clearly-stated list of dependencies. Ideally these should be handled with an automated package management solution.

Good: A package management file such as a Gemfile or package.json or equivalent
OK: A list of dependencies to install
Bad (not acceptable): Reliance on other software not listed by the authors

Example usage

The authors should include examples of how to use the software (ideally to solve real-world analysis problems).

API documentation

Reviewers should check that the software API is documented to a suitable level. This decision is left largely to the discretion of the reviewer and their experience of evaluating the software.

Good: All functions/methods are documented including example inputs and outputs
OK: Core API functionality is documented
Bad (not acceptable): API is undocumented


Authors are strongly encouraged to include an automated test suite covering the core functionality of their software.

Good: An automated test suite hooked up to an external service such as Travis-CI or similar
OK: Documented manual steps that can be followed to check the expected functionality of the software (e.g. a sample input file to assert behaviour)
Bad (not acceptable): No way for you the reviewer to check whether the software works

Community guidelines

There should be clear guidelines for third-parties wishing to:

  • Contribute to the software
  • Report issues or problems with the software
  • Seek support


Include here some examples of well-documented software for people to review.


Reviewers are expected to install the software they are reviewing and to verify the core functionality of the software.

Other considerations

An important note about 'novel' software

Submissions that implement solutions already solved in other software packages are accepted into JOSS provided that they meet the criteria listed above and cite prior similar work.

What happens if the software I'm reviewing doesn't meet the JOSS criteria?

We ask that reviewers grade submissions in one of three categories: 1) Accept 2) Minor Revisions 3) Major Revisions. Unlike some journals we do not reject outright submissions requiring major revisions - we're more than happy to give the author as long as they need to make these modifications/improvements.

What about submissions that rely upon proprietary languages/development environments?

As outlined in our author guidelines, submissions that rely upon a proprietary/closed source language or development environment are acceptable provided that they meet the other submission requirements and that you, the reviewer, are able to install the software & verify the functionality of the submission as required by our reviewer guidelines.

If an open source or free variant of the programming language exists, feel free to encourage the submitting author to consider making their software compatible with the open source/free variant.

Editorial Board

Arfon Smith

Arfon Smith (@arfon), Editor-in-Chief

A lapsed academic with a passion for new models of scientific collaboration, he's used big telescopes to study dust in space, built sequencing pipelines in Cambridge and engaged millions of people in online citizen science by co-founding the Zooniverse.

Topic Editors

Lorena A Barba

Lorena A Barba (@labarba), Editor : Computational Science And Engineering, High Performance Computing

Associate Professor of Mechanical and Aerospace Engineering at the George Washington University, leading a research group in computational fluid dynamics, computational physics and high-performance computing. Member of the Board for NumFOCUS, a non-profit in support of open-source scientific software.

Jason Clark

Jason Clark (@jasonclark), Editor : Information Sciences, Semantic Web

Associate Professor, Librarian, and Head of Archival Informatics and Special Collections at Montana State University (MSU) Library, specializing in software development, metadata and data modeling, linked and structured data, search engine optimization, and interface design. You can find him on ORCID at and as @jaclark on Twitter.

George Githinji

George Githinji (@biorelated), Editor : Bioinformatics

Bioinformatician and researcher at the KEMRI-Wellcome Trust Research Programme one of the Major Wellcome-Trust Overseas Programmes. George works with the Virus Epidemiology and Control group and develops bioinformatics methods for understanding virus transmission patterns and evolution. He undertook his education in Kenya and is one of East-Africa's open source software developers with an keen interest in bioinformatics and reproducible research.

Melissa Gymrek

Melissa Gymrek (@mgymrek), Editor : Bioinformatics

Assistant professor in Computer Science and Engineering and Medicine at UC San Diego with a research background in population genetics and bioinformatics. Interested in best practices for reproducible and open computational science and in how to take advantage of online media to change the face of scientific publishing.

Lindsey Heagy

Lindsey Heagy (@lheagy), Editor : Geoscience, Geophysics

Geophysicist in the Geophysical Inversion Facility at the University of British Columbia. Her research background is in computational geophysics and inverse problems. She contributes to geoscience-focused Python packages and develops open-source educational resources in the geosciences.

Kathryn Huff

Kathryn Huff (@katyhuff), Editor : Nuclear Engineering, Energy Engineering

Kathryn Huff is an Assistant Professor in Nuclear, Plasma, and Radiological Engineering at the University of Illinois at Urbana-Champaign. Her research focuses on modeling and simulation of advanced nuclear reactors and fuel cycles. She also advocates for best practices in open, reproducible scientific computing.

Daniel S. Katz

Daniel S. Katz (@danielskatz), Editor : Computer Science

Works on computer, computational, and data reseach at NCSA, GSLIS, and ECE at the University of Illinois at Urbana-Champaign, and has a strong interest in studying common elements of how research is done by people using software and data.

Thomas J. Leeper

Thomas J. Leeper (@leeper), Editor : Social Sciences

A survey and experimental methodologist currently working as Associate Professor in Political Behaviour at the London School of Economics and Political Science. His research focuses on the effects of information on public opinion, as well as techniques and tools for analyzing quantitative survey and experimental data. He has published more than thirty R packages on CRAN, and has authored and contributed to numerous other open source projects.

Christopher R. Madan

Christopher R. Madan (@cMadan), Editor : Psychology, Neuroimaging

Assistant Professor in the School of Psychology at the University of Nottingham. Studying human memory and decision making using cognitive psychology and neuroimaging approaches, and developing novel computational methods along the way.

Abigail Cabunoc Mayes

Abigail Cabunoc Mayes (@acabunoc), Editor : Open Science

Lead Developer at the Mozilla Science Lab. Abby has led development on various open source projects for science including Contributorship Badges for Science and WormBase. With a background in bioinformatics and computer science, she builds tools that use the web to move science forward.

Kevin M. Moerman

Kevin M. Moerman (@Kevin-Mattheus-Moerman), Editor : Image

Biomechanical and design engineer. Program manager for mechanical interfaces at MIT Media lab department of Biomechatronics. Developing computational methods for prosthetic device design. GIBBON code developer.

Kyle Niemeyer

Kyle Niemeyer (@kyleniemeyer), Editor : Computational Combustion, Fluid Dynamics

Mechanical engineer in the School of Mechanical, Industrial, and Manufacturing Engineering at Oregon State University. Computational researcher in combustion, fluid dynamics, and chemical kinetics, with an interest in numerical methods and GPU computing strategies.

Pjotr Prins

Pjotr Prins (@pjotrp), Editor : Bioinformatics, Reproducible Research, Software Deployment, High Performance Computing

Bioinformatician at large and director of and a visiting research fellow of The University of Tennessee Health Science Center and the Personal genomics and bioinformatics Department of Human Genetics of the University Medical Centre Utrecht. Writing software is Pjotr's core business in academia. He loves programming languages and he is involved in a wide range of free and open source software projects. He guides students to write software and, every year, he is a mentor and organisation administrator in the Google Summer of Code.

Karthik Ram

Karthik Ram (@karthik), Editor : Biodiversity Informatics, Data Science

A quantitative ecologist and data scientist at UC Berkeley' Institute for Data Science, his research focuses on food web dynamics, open science, open data, and reproducible research.

Ariel Rokem

Ariel Rokem (@arokem), Editor : Neuroscience, Machine Learning, Computational Social Science

Trained in cognitive neuroscience (PhD: UC Berkeley, 2010) and computational neuroimaging (Postdoc, Stanford, 2011-2015), Ariel Rokem is now a data scientist at the University of Washington eScience Institute, where he continues to develop software for the analysis of human neuroimaging data, develops tools for reproducible and open research practices, and collaborates with researchers from a variety of fields to advance data-intensive research.

Tracy Teal

Tracy Teal (@tracykteal), Editor : Bioinformatics

Executive Director of Data Carpentry and Adjunct Professor in the BEACON Center for the Study of Evolution in Action at Michigan State University. Her research background in is microbial metagenomics and bioinformatics, and she has been a developer and contributor to several open source bioinformatics projects. She also focuses on best practices in data analysis software development.

Roman Valls Guimera

Roman Valls Guimera (@brainstorm), Editor : Bioinformatics, Computer Science

Research software engineer working at the UMCCR in Melbourne, Australia. Likes to tap into many fields of science and computing including deployable and reproducible scientific software in both HPC and Cloud computing environments for scientific workflows and data analysis. In previous gigs enacted NeuroStars a Q&A site for its growing neuroscience community and also mentored different students via the Google Summer of Code program. More recently, self taught embedded systems design and RF engineering among other hobbies.

Jake Vanderplas

Jake Vanderplas (@jakevdp), Editor : Astronomy, Machine Learning

Astronomer exploring the role of data science in academia at University of Washington's eScience Institute. Core contributor to scikit-learn and other science-focused Python packages.

Jed Brown

Jed Brown (@jedbrown), Editor : Computational Science And Engineering, Geophysics, High Performance Computing

Assistant Professor of Computer Science at the University of Colorado Boulder leading a research group developing scalable algorithms and sustainable software for prediction, inference, and design via high-fidelity and multiscale physically-based models. He is a core developer of PETSc.

Cost and Sustainability Model

The Journal of Open Source Software is an open access journal committed to running at minimal costs, with zero publication fees (article processing charges) or subscription fees.

Under the NumFOCUS nonprofit umbrella, JOSS is now eligible to seek grants for sustaining its future. With an entirely volunteer team, JOSS is seeking to sustain its operations via donations and grants, keeping its low cost of operation and free service for authors.

In the spirit of transparency, below is an outline of our current running costs:

  • Annual Crossref membership: $275 / year
  • JOSS paper DOIs: $1 / accepted paper
  • JOSS website hosting (Heroku): $19 / month

Assuming a publication rate of 200 papers per year this works out at ~$3.50 per paper ((19*12) + 200 + 275) / 200 .

Content Licensing

Creative Commons Licence Copyright of JOSS papers is retained by submitting authors and accepted papers are subject to a Creative Commons Attribution 4.0 International License.

Any code snippets included in JOSS papers are subject to the MIT license regardless of the license of the submitted software package under review.