Settling a naming convention for versioning numbers

[mrshirts]

Right now, published versions (for the first time) are v1.0. But we should have some sort of naming convention.

[mrshirts]

Dan Siderius writes as his proposal.

We require a version identification scheme for LiveCoMS manuscripts according the general "vY.X" format, where Y is the major version and X is the minor version.

Major version number must follow a strict order:
0 indicates a version of the manuscript prior to acceptance in LiveCoMS.
1 indicates the first version reviewed and accepted (in final form) for publication in LiveCoMS
2 indicates the second version reviewed and accepted (in final form) for publication in LiveCoMS
3 . . . and so forth
An increment in the version number indicates that the manuscript has been peer reviewed.

The Minor version number should increment with each non-trivial (e.g., more than a spelling, grammar, or formatting correction) revision to the manuscript.

For example, versioning for an article in LiveCoMS could proceed as:
v0.1: Some pre-submission version of the manuscript
v0.3: First version submitted to LiveCoMS
v0.5: Revision following peer-review
v1.0: Accepted form of paper, following all editor- and publisher-requested revisions
v1.1: One section of v1.0 text is revised for clarity or textual accuracy
v1.14: Fourteenth non-trivial revision to v1.0 text
. . . continued. . .
v2.0 : Second Accepted form of paper, following all editor- and publisher-requested revisions
etc.

---

I'm wavering on some tag to indicate that the paper is being revised in preparation for an increment in the major version. It's a bit of a philosophical question; should a version of the manuscript that is being prepared for a new review be considered a minor revision of the last reviewed version, or a pre-release/alpha version of the 2.0 manuscript? We may need to have an intermediate indicator, such as:

v2.0-alpha1: indicates a pre-submission version of the 2.0 manuscript.

[mrshirts]

Dan Zuckerman writes:

Dan, I like what you have between the dashed lines, but I think adding an 'alpha' descriptor would be too complicated. However, perhaps we can mandate v0.9 = ASAP version, if that makes sense to everyone. --Dan Z

[mrshirts]

I think that v1.0, v2.0, v3.0 for peer-reviewed versions is needed. And then in-between, non trivial versions get minor revisions. I would let the authors increment however they need, as long as the major version is the published version. Pre-acceptance, it's version v0.x

I'm not that excited about the ASAP version being 0.9. One practical consideration is that the version number is part of the title, and Scholastica creates the URL using that version. Could be messy. The other is the idea that the ASAP is essentially the version pre-galley proofs, and it's not REALLY a new major version.

[dwsideriusNIST]

Dan Zuckerman writes:

... but I think adding an 'alpha' descriptor would be too complicated. However, perhaps we can mandate v0.9 = ASAP version, if that makes sense to everyone. --Dan Z

Michael Shirts writes:

...Pre-acceptance, it's version v0.x

Sorry to make this a sticking point... I think the guidance text needs to address a paper that is moving toward an increment in the major version. In Semantic Versioning, the "alpha" (or 'beta', 'dev', etc.) descriptor is used, but that is predicated by rules about API backwards-compatibility. We don't really have that constraint here, obviously. But at the same time, the last "v1.XYZ" versions prior to v2.0 might barely resemble the organically evolved v1.0 text if the authors decided to substantially revise the document. I don't think there is a right answer here, but I would like to clear about the meaning of the version number.

[mrshirts]

In my mind, the firm rules have to be:

• 1.0, 2.0, 3.0, 4.0, etc. are the peer-reviewed versions
• Their private versions that build off of these are 1.x, 2.x, 3.x, 4.x, etc.
• If people are preparing something to be submitted, then it's <1.0.

Beyond that, I think we just want people to version their intermediate documents, and I'm not sure that it really matters how they do it, or that we want to micromanage.

[davidlmobley]

I think strict requirements about major versions, with suggested guidelines for minor versions as per Dan S.'s comments.

One thing that's slightly complicated is that if the ASAP version needs to be 1.0 for URL reasons, but the published version also needs to be 1.0, then we potentially have two different "v1.0" versions with different dates, which can confuse people. Not clear to me how best to avoid confusion...

[dwsideriusNIST]

I think strict requirements about major versions, with suggested guidelines for minor versions as per Dan S.'s comments.

Sorry to keep bringing this up. What is our preference for papers transitioning from vX.Y to v(X+1).0?

One thing that's slightly complicated is that if the ASAP version needs to be 1.0 for URL reasons, but the published version also needs to be 1.0, then we potentially have two different "v1.0" versions with different dates, which can confuse people. Not clear to me how best to avoid confusion...

There's actually a bit more possible confusion than that. Any time the PDF is recompiled, the date changes; the git log is a necessity for understanding the change. We could revise the frontmatter from "This version dated November 30, 2018" to "This version was compiled on November 30, 2018".

(I'd also change the date convention to international standard.)

[dmzuckerman]

If ASAP needs to be v1.0, can we make published version "v1.0.published"? I assume the version "number" does not absolutely have to be a number. I agree we don't want two v1.0 versions.

Presumably, any time the PDF is recompiled, that's done for a reason, even if extremely minor. We could automatically alert readers to this by including a date in the version number: "v1.0.06dec2018" I think readers would infer that an unchanged numerical value for the version number implies they don't need to worry about big changes ... but at least we do 'full disclosure'.

[mrshirts]

So, I agree that the ASAP version needs to look differently than the final published version. I don't know that the number needs to change, since the document is really just supposed to be proofed between the two versions. I think we can call it v1.0, as long as there is something at the bottom saying "ASAP version". Perhaps if there is a template flag that can switched, then when moving to the new version, they just switch that, and the issue and version are filled in there.

…

On Thu, Dec 6, 2018 at 3:07 PM dmzuckerman ***@***.***> wrote: If ASAP needs to be v1.0, can we make published version "v1.0.published"? I assume the version "number" does not absolutely have to be a number. I agree we don't want two v1.0 versions. Presumably, any time the PDF is recompiled, that's done for a reason, even if extremely minor. We could automatically alert readers to this by including a date in the version number: "v1.0.06dec2018" I think readers would infer that an unchanged numerical value for the version number implies they don't need to worry about big changes ... but at least we do 'full disclosure'. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#176 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEE31F_h5QHC4nvObh6v3DYfizirRnVKks5u2ZUZgaJpZM4Y461U> .

[dwsideriusNIST]

Here's a trial: https://github.com/dmzuckerman/Sampling-Uncertainty/blob/ASAP_test/main.pdf (look at the footer)

Question: Do we put "ASAP Version" OR "citation information" or a combination of the two? An if/then tree would be helpful.

ACS doesn't actually explicitly state ASAP in an article that is typeset, but without volume/issue/etc information; it just has placeholders for the citation information.

[dmzuckerman]

Works for me.

[mrshirts]

It will probably have a DOI at that point. Which, of course, does mean it will have an issue / volume as well. But if we put the issue/volume up there, then it looks kind of weird (it has an issue and volume, but is ASAP). So I would probably say "Living J. Comp. Mol. Sci, ASAP version" and then when published "Living J. Comp. Mol. Sci, (citation info) would work better.

Also, should citation info be Year, volume, issue, number, or volume, issue, number, year?

[dwsideriusNIST]

OK, that's a workable format; here's my thought as far as if-then-else:

if "nothing":
-> nothing in the right or left sides of the footer
elseif "ASAPversion":
-> include received date, accepted date, DOI, and "LiveCoMS ASAP Version" in footer
elseif "pubversion":
-> include received date, accepted date, DOI, and "LiveCoMS " in footer.

I went with "Year, volume (issue), number" in a blatant copying of ACS, no other reason. It's one line of code to change if desired.

[davidlmobley]

I like your proposals, @dwsideriusNIST .