JOSS: A Developer-Friendly Journal and Submission Platform

What JOSS Solves for Research Software Authors

The Journal of Open Source Software addresses a specific problem in academic publishing: research software often needs a formal publication, but preparing a conventional software paper can require substantial writing work. JOSS describes itself as a developer-friendly academic journal for research software packages. Its stated audience is therefore researchers who have built software and need a peer-reviewed publication record, rather than developers looking for a code hosting service or a journal for general computer science research.

The project states that submissions go through a formal peer review process intended to improve the quality of the submitted software. After acceptance, a CrossRef DOI is minted and the paper is listed on the JOSS website. The README also says that well-documented software should require no more than an hour for paper preparation. That is a workflow claim from the project documentation, not a guarantee of review duration or acceptance.

JOSS is hosted at https://joss.theoj.org. The repository described here contains the submission tool and site. Review issues are handled in a separate repository, `openjournals/joss-reviews`, so an engineer should not confuse the application code with the public review record.

JOSS Submission and Review Architecture

Based on the repository layout, JOSS is a Rails application written primarily in Ruby. The top-level entries include `app/`, `bin/`, `config/`, `db/`, `lib/`, `spec/`, and `docs/`, along with `Gemfile`, `Gemfile.lock`, and `config.ru`. The development instructions use Rails commands such as `bin/rails db:create`, `bin/rails db:migrate`, and `bin/rails s`, which confirms that the project is intended to run as a server application rather than as a command-line converter or library.

The documented local data flow has three parts. PostgreSQL stores application data and receives database creation and migration commands. Elasticsearch provides search functionality. After Elasticsearch is running, the project creates an index and runs a Rails indexing command through Searchkick. The documented order is database setup, optional seed data, Elasticsearch index creation, search index population, and Rails server startup.

The README does not describe the internal models for submissions, reviewers, papers, or DOI registration. It also does not document deployment beyond the hosted service and the local development procedure. Consequently, the repository provides enough information to understand the operational dependencies, but not enough to make claims about the full submission state machine, review assignment logic, or production deployment topology.

Local Setup for the JOSS Rails Application

The README requires PostgreSQL and Elasticsearch to be installed and running locally before the application can work. The following sequence uses the exact commands and configuration names documented by the project. Run these commands from the repository root. The database commands require the development Rails environment, and the Elasticsearch request expects the service at `http://localhost:9200`.

Install the Ruby dependencies with Bundler:

bundle install

Set the Rails environment for the shell:

export RAILS_ENV=development

Create and migrate the PostgreSQL database:

bin/rails db:create
bin/rails db:migrate

The README marks demo data as optional and points to `db/seeds.rb`:

bin/rails db:seed

After Elasticsearch is running, create the documented index:

curl -X PUT http://localhost:9200/joss-production

The README notes that Elasticsearch's default security settings may need to be disabled by editing `config/elasticsearch.yml`. Then rebuild the application search indexes:

bin/rails searchkick:reindex:all

Finally, start the Rails server:

bin/rails s

The README does not specify the expected HTTP port or a browser URL for the local server, so the article does not invent either.

A First Real Use of the JOSS Submission Service

For a software author, the first practical use is the hosted submission workflow at https://joss.theoj.org, not the local Rails server. The README says that JOSS has a simple submission workflow and extensive documentation for preparing a submission. It does not provide a public API, CLI command, or sample submission payload, so the documented first step is to use the website and follow its submission documentation.

The project describes paper preparation as the point at which already documented software should be converted into a submission. The repository itself does not contain enough instructions to create an account, select a journal category, upload files, invite reviewers, or track a submission through its hosted interface. Those operations should be treated as website-specific details rather than inferred from the Rails code.

For contributors working on the application source, the README gives a separate development path. It asks contributors to fork the repository, create a feature branch, commit changes, push the branch, and create a pull request. The only exact command shown for that path is the branch example:

git checkout -b my-new-feature

The commit and push commands are also documented, but they are general Git operations rather than JOSS-specific runtime commands. This distinction matters because a prospective JOSS author and a prospective JOSS contributor interact with different parts of the project.

Operational Limits and Platform Dependencies

The main limitation for local use is infrastructure coupling. PostgreSQL and Elasticsearch are both mandatory according to the development instructions, and the application requires an index creation request plus a Searchkick reindex operation before it is considered ready. A developer who only wants to inspect the Ruby code must still account for these external services when attempting a functional local setup.

The Elasticsearch instructions also expose a configuration choice rather than a fully isolated development stack. The README says that default Elasticsearch security settings may need to be disabled in `config/elasticsearch.yml`. That is a local development note, not a recommendation for production. The documentation does not describe authentication, Elasticsearch version selection, production indexing, or backup procedures, so those areas remain unspecified.

The MacOS note documents a startup failure involving Objective-C initialization during a fork and provides one documented workaround:

export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES

This is presented as a response to a specific startup error and linked to a Rails issue. The README does not say that the variable is required on every MacOS system. It should therefore be treated as a conditional troubleshooting setting rather than a universal installation requirement.

JOSS is also not a general-purpose paper editor. The repository gives no details about automated formatting, collaborative manuscript editing, reference import, or manuscript versioning. Its stated scope is the journal and submission workflow for research software.

JOSS Compared With Code Review and Ordinary Hosting

JOSS differs from a code hosting platform because its stated purpose is academic publication and peer review. A hosting or issue-tracking service can store source code and discussions, but the JOSS README specifically describes a formal peer review process, a published paper listing, and DOI minting after acceptance. Those are journal outcomes, not repository features.

It also differs from a conventional journal workflow by presenting a developer-oriented submission process and by stating that documented software should reduce paper preparation time. That design does not mean that review is informal. The same document explicitly calls JOSS an academic journal and says acceptance follows a formal review process.

The separate reviews repository is another important architectural distinction. Contributors looking for the actual review records should use `https://github.com/openjournals/joss-reviews/issues`, while developers running the site should work in `openjournals/joss`. Keeping these repositories separate can make the public review trail easier to locate, but it also means that understanding a paper's review history requires visiting another repository.

The MIT license applies to this repository. The README does not state licensing terms for submitted papers, review records, hosted content, or third-party dependencies. Any organization using JOSS should therefore distinguish the repository's MIT license from the terms governing journal content and separately review the relevant site or contributor terms. This is a scope observation, not legal advice.

Maintenance and Upgrade Signals in the Repository

The repository is not archived. Its last push was on 2026-10-16, so the available maintenance signal is recent repository activity rather than a published GitHub release history. The repository has no GitHub releases, so no release tag or release note is identified. The README also does not document a release schedule or an upgrade procedure.

For operators, an upgrade assessment must therefore begin with the dependency files, especially `Gemfile` and `Gemfile.lock`, and with the database migration files under `db/`. The existence of those files confirms that dependency and schema changes are part of the project layout, but the README does not say how migrations should be applied during an upgrade or how Elasticsearch indexes should be migrated. The documented development commands provide a starting point, not a production upgrade runbook.

The hosted service may have its own operational process, but the README does not describe service availability, hosting architecture, backups, or support commitments. A prospective maintainer should not infer those properties from the presence of a hosted website.

Editorial conclusion

JOSS is appropriate for research software authors who need a formal academic publication process and are prepared to provide documentation, a repository, and a reviewable paper. It is less suitable for developers seeking only hosting, release management, or a general-purpose code review service. Before adopting it, verify that PostgreSQL, Elasticsearch, the required Ruby dependencies, and the indexing configuration work in the target environment.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. openjournals/joss on GitHub
4. Project website
5. README