Single-Source Publishing Workflow of the Journal of Open Source Software

The Journal of Open Source Software (JOSS) is a scholar-led, diamond open access journal. It was created to fill a niche in the academic publishing landscape, and to allow authors of scientific open source software to showcase their work and to create citable papers, all to support and encourage the open development of scientific applications.

The JOSS team also created an umbrella organization, Open Journals, so that the infrastructure and practices developed for JOSS could be shared across a collection of community-organized and volunteer-led journals.

Description

The journal targets tech-savy scientists who write programs as part of their research. It was therefore sensible to use technology commonly used in software development. The willingness of authors to follow detailed instructions lessen the editors’ and reviewers’ workload via heavy use of automation and strict guidelines.

Submission process

Authors write their paper in Markdown, a popular light-weight markup language, with citations captured in BibTeX, a widely-used style for reference management. The paper must be placed alongside the software that it describes in a Git repository. Submission requires providing the URL of the software repository; the process can only be initiated with an ORCID account, i.e., with a persistent identifier.

Reviewing

All reviews happen on GitHub, a proprietary platform that can be used free of charge. The “submission issue threads” are open and can be read by everybody. The threads are started with basic information on the software and the paper, including statistics on the code and some automatic checks on for adherence to the author guidelines.

The system builds heavily on a bespoke chatbot called editorialbot, built with the Buffy framework. Among other things, it generating PDFs, checking references for missing DOIs, and changing the status of the submission (pre-review, review, recommend-accept, accepted, published).

Editorialbot

The capabilities of the editorialbot are best described by looking at some typical examples. E.g., to add another user as a reviewer, an editor would write a comment in the review thread with

@editorialbot add @username as reviewer

The editorialbot will then send the necessary requests, notifactions, and handle the internal book-keeping. This includes permission management.

The system also allows to schedule a reminder for a reviewer:

@editorialbot remind @username in 2 weeks

Other typical commands are “@editorialbot generate pdf”, which will generate a draft PDF, and “@editorialbot check references”, which verifies the given references and can suggest DOIs for entries for which none is given.

The final reviewer and editor decisions are also handled via the editorialbot by issuing commands like “@editorialbot action”, where action could be recommend-accept, accept, or reject. The editorialbot triggers the necessary processes for each action, including the publishing process after acceptance.

Publishing

During publishing, the editorialbot amends the author-provided metadata with additional metadata, e.g., the article’s DOI. This YAML data is combined with the submitted Markdown file and the BibTeX, and sent to the publishing pipeline. Artifact generation, website updates, and social media announcements all happen automatically.

Formats

The paper must be written in Markdown, specifically in the Markdown flavor supported by pandoc, a near-universal document converter. References must be given in BibTeX format, while metadata is kept in YAML.

The pipeline produces PDF/A-1b, HTML, JATS XML, and CrossRef XML, even though the HTML-artifacts are currently unused.

Software

The software developed specifically for this project was written by volunteers or was funded via a grant by the Sloan Foundation.

All components, except for the GitHub platform, are open source. For example, Buffy, the software behind editorialbot, can be found at https://github.com/openjournals/buffy.

Publishing artifacts are produced via pandoc. PDF production additionally leans on LuaLaTeX. The pipeline software is called Inara.

A detailed description of all the software components developed and in use by JOSS can be found in the Open Journals’ infrastructure documentation repository.

Staffing requirements

At the time of writing, all people involved in the project are unpaid volunteers. This includes the editors, reviewers, and software maintainers.

Editors must be familiar with the reviewer management system, while reviewers should be comfortable with GitHub and with using editorialbot.

The initial setup required the design of a LaTeX layout and the conversion to a pandoc template. This knowledge is also required for updates and changes to the layout.

Extra requirements imposed on authors

Authors must include specific sections in their paper, e.g. “Statement of Need”. Article metadata, including author affiliations, must be given in a specific YAML format as part of the Markdown file. Detailed docs are available for all steps.

Costs

The main cost centers are server costs as well as payments to CrossRef for DOIs. Publishing costs per article are below 5€.

Challenges and Trade-Offs

The project rests on a commercial service that’s offered free of charge. Continued operations depend on the service provider’s willingness to allow this kind of usage. Migrating to a different service would require considerable efforts and software updates, but little additional operational cost.