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

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.

NumFOCUS

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 paper.md 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 paper.md adapted from "Gala: A Python package for galactic dynamics",
  Adrian M. Price-Whelan, http://doi.org/10.21105/joss.00388:

---
title: 'Gala: A Python package for galactic dynamics'
tags:
  - Python
  - astronomy
  - dynamics
  - galactic dynamics
  - milky way
authors:
  - 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
affiliations:
 - 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
``astropy.coordinates``).

``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
[rMarkdown](http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html)
format.

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:

  @article{Pearson:2017,
  	Adsnote = {Provided by the SAO/NASA Astrophysics Data System},
  	Adsurl = {http://adsabs.harvard.edu/abs/2017arXiv170304627P},
  	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}

  @book{Binney:2008,
  	Adsnote = {Provided by the SAO/NASA Astrophysics Data System},
  	Adsurl = {http://adsabs.harvard.edu/abs/2008gady.book.....B},
  	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}

  @article{zenodo,
  	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 = {http://dx.doi.org/10.5281/zenodo.833339}}

  @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 = {http://adsabs.harvard.edu/abs/2016A%26A...595A...1G},
  }

  @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 = {http://adsabs.harvard.edu/abs/2013A%26A...558A..33A}
  }

Submission then is as simple as:

• Filling in the short submission form
• Waiting for reviewers to be assigned over in https://github.com/openjournals/joss-reviews

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 http://choosealicense.com 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

Documentation

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

Tests

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

Examples

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

Functionality

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

Topic Editors