PeerJ R2C14

[kyleniemeyer]

Section 6

The last paragraph is very long, a bit unclear and unsatisfactory in its ending. Is there a process foreseen to come to a choice to deal with this for JOSS?

[danielskatz]

The last paragraph is currently:

Beyond roles and responsibilities for the editors, and improvements to the JOSS tools and infrastructure, we will take on the more tricky questions about publishing software. One of these is how to handle new software versions. Unlike traditional research articles, which once published are static, software needs to change over time, at least for maintenance and to avoid software rot/collapse (where software stops working because of changes in the environment, such as dependencies on libraries or operating system). Because software needs to be under continuous development for maintenance, and because the potential uses of the software are seldom known at the start of a project, the need or opportunity arises to add features, improve performance, improve accuracy, etc. Once one or more changes have been made, software developers frequently rename the software with a new version number. Following semantic versioning practices (where software versions are of the form MAJOR.MINOR.PATCH, see semver.org), a small set of changes may lead to an increased version of the software; i.e., the patch element of the version number is incremented, or possibly the minor element is incremented if enough changes have been made. Once the developers determine the set of changes has grown large enough or if the API changed in a way that makes downstream software unable to use it any longer (a backward-incompatible change), the major version number of the software will be incremented. Each change may be made by a different developer, who may be making their first contribution to the software. This implies that a new version might correspond to a new set of authors if the software is published. Exactly how this process translates to JOSS is not yet clear. The editorial board is supportive of a model where a new JOSS article is published with each major version, but the details of how this would work, and whether it would be accepted by both developers and users (corresponding to JOSS authors and readers, respectively) is unknown.

I don't think it's unclear, but I agree that it is a bit "unsatisfactory in its ending." Maybe we can change the last sentence to:

The editorial board will accept a new JOSS article published with each major version or even a minor version if the changes seem significant enough to the editor and reviewer(s), but whether this will be satisfactory to the needs of both developers and users (corresponding to JOSS authors and readers, respectively) is unknown.

[kyleniemeyer]

OK, I adopted @danielskatz's new last sentence, and also tried to condense the paragraph in a few other places (including moving the description of semantic versioning to a footnote); I think this helps make it a little shorter and also the ending more satisfactory.

Beyond roles and responsibilities for the editors, and improvements to the JOSS tools and infrastructure, we will take on the more tricky questions about publishing software. One of these is how to handle new software versions. Unlike traditional research articles, which once published are static, software likely changes over time, at least for maintenance and to avoid software rot/collapse (where software stops working because of changes in the environment, such as dependencies on libraries or operating system). Furthermore, because potential uses of the software are seldom known at the start of a project, the need or opportunity arises to add features, improve performance, improve accuracy, etc. After making one or more changes, software developers frequently rename the software with a new version number. Following semantic versioning practices, a small set of changes may lead to an increased version of the software; i.e., the patch element of the version number is incremented, or possibly the minor element is incremented if enough changes have been made. Once the developers determine the set of changes has grown large enough or if the API changed in a way that makes downstream software unable to use it any longer (i.e., a backward-incompatible change), the major version number of the software will be incremented. Each change may be made by a different developer, who may be making their first contribution to the software. This implies that a new version might correspond to a new set of authors if the software is published, but this process may not translate clearly to JOSS. The editorial board will accept a new JOSS article published with each major version or even a minor version if the changes seem significant enough to the editor and reviewer(s), but we do not know if this will be satisfactory to the needs of both developers and users (corresponding to JOSS authors and readers, respectively).

[danielskatz]

Suggestions:

Beyond roles and responsibilities for the editors, and improvements to the JOSS tools and infrastructure, we will take on the more tricky questions about publishing software. One of these is how to handle new software versions. Unlike traditional research articles, which once published are static, software usually changes over time, at least for maintenance and to avoid software rot/collapse (where software stops working because of changes in the environment, such as dependencies on libraries or operating systems). Furthermore, because all potential uses of the software are not known at the start of a project, the need or opportunity arises to add features, improve performance, improve accuracy, etc. After making one or more changes, software developers frequently rename the software with a new version number. Following semantic versioning practices, a small set of changes usually leads to an increased version of the software; i.e., the patch element of the version number is incremented, or possibly the minor element is incremented if enough changes have been made. Once the developers determine the set of changes has grown large enough or if the API has changed in a way that makes downstream software no longer able to use it without changes (i.e., there has been a backward-incompatible change), the major version number of the software will be incremented. Each change may be made by a different developer, who may be making their first contribution to the software. This implies that a new version might correspond to a new set of authors if the software is published, but this process may not translate clearly to JOSS. The editorial board will accept a new JOSS article published with each major version or even a minor version if the changes seem significant enough to the editor and reviewer(s), but we do not know if this will be satisfactory to the needs of both developers and users (corresponding to JOSS authors and readers, respectively).

And I'm not very sure about this last sentence, specifically, the "but we do not know ..." part.

[arfon]

Beyond roles and responsibilities for the editors, and improvements to the JOSS tools and infrastructure, we will take on the more tricky questions about publishing software. One of these is how to handle new software versions. Unlike traditional research articles, which once published are static, software usually changes over time, at least for maintenance and to avoid software rot/collapse (where software stops working because of changes in the environment, such as dependencies on libraries or operating systems). Furthermore, because all potential uses of the software are not known at the start of a project, the need or opportunity arises to add features, improve performance, improve accuracy, etc. After making one or more changes, software developers frequently update the software with a new version number. Over time, the culmination of these changes may result in a major update to the software and with many new contributors a new version might correspond to a new set of authors if the software is published. This process may not translate clearly to JOSS: The editorial board will accept a new JOSS article published with each major version or even a minor version if the changes seem significant enough to the editor and reviewer(s), but it is not yet clear whether this will be satisfactory to the needs of both developers and users (corresponding to JOSS authors and readers, respectively).

OK, I've tried to shorten this paragraph a little (I've dropped the detail about semantic versioning) and have modified the last sentence a little. Thoughts?

[danielskatz]

ok.

[kyleniemeyer]

I don't like the "it is not yet clear", because it hides that it's not yet clear to us, hence the active phrasing "we do not yet know"...

[kyleniemeyer]

(but I agree we don't need to get into details on semantic versioning, that isn't important for what we are trying to say)

[kyleniemeyer]

OK, here is what I put in the paper (adopted from what @arfon wrote above, but with that long final sentence broken up):

Beyond roles and responsibilities for the editors, and improvements to the JOSS tools and infrastructure, we will take on the more tricky questions about publishing software, such as how to handle new software versions. Unlike traditional research articles that remain static once published, software usually changes over time, at least for maintenance and to avoid software rot/collapse (where software stops working because of changes in the environment, such as dependencies on libraries or operating system). Furthermore, because all potential uses of the software are not known at the start of a project, the need or opportunity arises to add features, improve performance, improve accuracy, etc. After making one or more changes, software developers frequently update the software with a new version number. Over time, the culmination of these changes may result in a major update to the software, and with many new contributors a new version might correspond to a new set of authors if the software is published. However, this process may not translate clearly to JOSS. The editorial board will accept a new JOSS article published with each major version or even a minor version if the changes seem significant enough to the editor and reviewer(s), but we do not yet know if this will satisfy the needs of both developers and users (corresponding to JOSS authors and readers, respectively).

I do think we should say "but we do not yet know if this will satisfy the needs of both developers and users" because that's more honest.

[arfon]

👍🏻