No (obvious) way of submitting a paper that doesn't live in the software repository

[logological]

The Submission Requirements section of the JOSS Documentation makes it clear that it merely preferable, not necessary, for the submitted paper to be hosted in the same repository as the software it describes:

Your paper (paper.md and BibTeX files, plus any figures) must be hosted in a Git-based repository, ideally together with your software.

I think this is a sensible choice—sometimes it is not convenient or practical for the paper to be placed directly in the software repository.

The problem is that the journal's submission form presents contributors with no (obvious) way of submitting a paper that isn't contained in the software repository. There is only one field for specifying a repository, and it's not clear whether this is meant to be for the software or for the paper.

Please consider updating the submission form to account for the case that the paper is hosted in a different repository than the software. This could be done, for example, by changing the label of the existing repository field from "Repository address (git repository address only)" to "Software repository address (git repository address only)", and adding an additional, optional repository field labelled "Paper repository address (if different from the software repository address)". Alternatively, the instructions for the "Message to editors" field could be updated to ask contributors to specify the paper repository address in the event that it differs from the software repository address.

[arfon]

Thanks for flagging this.

The Submission Requirements section of the JOSS Documentation makes it clear that it merely preferable, not necessary, for the submitted paper to be hosted in the same repository as the software it describes:

This is correct, but I would say it's a strong preference, and something I'm actually thinking we should make a requirement as when a paper submission is not in the software repository it actually makes a bunch of work for the editorial team which runs counter to our goals of trying to run a low-cost journal.

One potential work around - Whedon (our bot) can compile papers that are buried deep in a nested folder within a repository, or even on a different branch (which never gets merged to master) so we're quite flexible about where this paper can live.

Could you say a little more about why it's not convenient for your situation to have the paper in the same repository as the software?

[logological]

It's not an absolute showstopper for me, though here are some reasons why contributors may find this inconvenient:

• Some people have their packaging scripts set up to include the project's commit history in a user-visible ChangeLog file (for example, by invoking GNU's gitlog-to-changelog in Automake's Makefile.am), which they don't want polluted by a bunch of messages about fixing typos and whatnot in a paper that isn't technically part of the software's technical documentation.
• Commits affecting only the paper may nonetheless trigger a (potentially time- and CPU-intensive) build if the project uses some continuous integration system.
• Some projects specify a blanket licence for the documentation, and that licence may differ from the CC BY licence for the journal paper. So it will be a bit of extra work to document the exception (or maybe more than a little extra work, if the project uses a finicky automated licence checker like Apache Rat).
• Some contributors may keep all their software repositories in one place and all their paper repositories in another place, so mixing the code and paper violates this separation.

Using a separate branch for the paper may avoid some or all of these issues, though it has the disadvantages of (1) being an abuse of the very notion of branches, which software engineering purists will find off-putting, and (2) not actually being supported in the JOSS submission form. (The preview page allows one to specify both a repository and a branch name, but the submission form has no field for the branch.)

[jedbrown]

Addressing your first points, it's very reasonable (and I'd say recommended for large projects) to have the paper in a branch that gets squash-merged upon acceptance. The requirement to make a post-review release is more onerous IMO, but we haven't seen a lot of push-back.

[logological]

I agree, that's probably reasonable for most contributors.

By the way, quite possibly this issue is a duplicate of Issue #506, which I discovered just now.