Support version types and summaries

[NateWr]

Requirements specified by ORE

• ORE file: Tender_Specifications _vf_V1.pdf; tbd
• PKP file: OSS ORE Technical Tender-1.pdf; tbd

Requirements clarification

• When an Editor sends a file to the Text Editor, can the Editor rename the version from "Unassigned Version" to a custom name?
  

Decision: When a file is sent to the text editor and the editor selects the unassigned version, they have the option to assign a stage and version, which will rename the unassigned version accordingly.

• When an Editor sends a file to the Text Editor, will we allow them to add a new version or edit the name of an existing version in the Article Stage dropdown?
  

Decision: we are sticking to the NISO Journal Article Versioning and not allowing the editors to customise the stage names in the settings

• In the Text Editor view (at the top), is the "Notes" field useful to have?
• When upgrading from previous project version with multiple versions created what will the new versions be converted to? Version of record 1.0 and 1.1 or Version of record 1.0 and 2.0?
• If I was to use the native XML import/export tool to move one submission with multiple verions created to another journal on the same install would that be handled? Should we create a story for handling this scenario?

Workflows Affected by This Change

last edited: Jan 20, 2025

• Add a new option, "Send to Editor," under Workflow Stage > Files > More Options. This option will transfer the file to the Text Editor in the Publication tab.
• For every new submission, automatically create an "Unassigned Version" in the Publication tab.
• When a file is sent to the editor, a form will open to assign the Article Stage and Revision Significance to the version.

Detailed Specs

Prototype Link - https://www.figma.com/proto/Wf7sDlUg2372jaKKTJ0Mgz/OJS-3.4-3.5?page-id=7200%3A7069&node-id=11220-12087&viewport=1397%2C-17519%2C0.18&t=RxHnZdbAjRALzmve-1&scaling=min-zoom&content-scaling=fixed&starting-point-node-id=11220%3A12087

The user journey is created keeping in mind the following considerations

• The text editor (not in scope here -- see Integrate fulltext HTML editor #10419) has been specifically designed for use by journal management staff, as outlined during the Turin Sprint discussions. It’s not intended for use by authors, keeping the workflow focused and streamlined for editorial teams.
• The established OJS workflow remains intact and is further enhanced to support the integration of the text editor. Even if a journal chooses not to adopt the text editor, there’s no need to learn anything new—the familiar workflow stays the same.
• Additionally, we’ve incorporated more detailed features to manage version information, drawing on the guidance provided in the NISO Journal Article Versions draft (link to resource).

Explanation of the User Flow

1. When the user comes to the Submission Workflow Page from the dashboard

• When a new submission comes in, we automatically create a version called the "Unassigned Version". This is because, at this stage, there’s no version history, and we haven’t yet asked the editor to specify a version name. To keep things simple and avoid unnecessary complexity, we opted to create an "Unassigned Version" as a default starting point. Further reasoning for this point, There will always be at least one version. Without a version, there is no title, there is no abstract, there are no authors. It's not possible to delete the only version in a submission.
• There are two ways to create a new version:
  • Sending a document/file to the text editor during the publication workflow. (Out of scope here -- see Integrate fulltext HTML editor #10419)
  • Manually creating a new version by clicking on "Create a New Version" in the Publication tab.
• Publishing a submission does not create a new version; it just flags an existing one as "published". We’ve designed these options to give users flexibility while keeping the process straightforward.

2. File taken from the submission workflow stage to the text editor in the publication section

https://youtu.be/1DIkq3jIv-8

• When a file from the submission workflow is taken to the Text Editor, two things can happen:

1. The editor decides to use the current "Unassigned Version":
   • The editor can proceed with editing the text as part of this default version.
   • If the editor chooses, they’ll be prompted to assign an article stage and revision significance. If these options are selected, the unassigned version is updated accordingly.
   • If the editor decides not to assign these options, that’s perfectly fine too—the version will remain "Unassigned."
2. The editor creates a new version:
   • By clicking "Create a New Version," the editor can name the new version based on their selections. The original "Unassigned Version" is retained as-is for reference.

If a new type of stage is created by default it is always major version even if a minor version is selected in the start

Other Considerations

1. Moving submission from one stage to another is not going to create a version by default
2. A submission will only ever be published as what the editor designates a stage to it. We should block them from publishing something without a stage being designated -- so an Unassigned Version should not be possible to publish as-is
3. If an Article Stage does not exist, the Revision Significance will default to Major Revision, and Minor Revision will not be an option. Minor Revision will only be available if an Article Stage with a Major Revision already exists.
4. Assigned Versions should be followed by the date format DD-MM-YYYY, while other versions—such as Accepted Manuscript, Submitted Manuscript, etc.—should follow the format M.m.

---

ARCHIVED UPDATES

Update (2024)

Goal: Enrich the metadata and presentation about journal article versions. This is a required feature for OSS ORE, and also an item of community interest.

NISO Journal Article Versioning

The NISO Journal Article Versioning group has posted a draft revision of the JAV standard, available here. The JAV working group's page is at niso.org.

They propose a versioning standard using a combination of Article Lifecycle Stage and Semantic Versioning).

From the draft, Article Lifecycle Stage includes the following stages:

• AO: Author’s Original
• SM: Submitted Manuscript
• AM: Accepted Manuscript
• PF: Proof
• VoR: Version of Record

Within each stage, they propose a major.minor version numbering, starting with 1.0 when the submission changes to a new stage.

Proposed Approach

• Adopt the proposed JAV approach to versioning:
  • Allow for versions to be designated to an Article Lifecycle Stage
  • Allow for versions to be designated as major or minor revisions
  • Allow for versions to receive semantic version numbering according to the above two
• With respect to JATS:
  • Per prior discussion, add support for an optional version summary (plain text field) that can be used to describe the revision -- like a commit log.
  • Review and adopt the recommendations in the JAV proposal with respect to JATS output -- see Appendix E.1.
• Review the current Open Research Europe platform to look for gaps.
• General changes required:
  • We'll need to introduce a modal to set/edit version details.
  • We'll need to make it easier to work with multiple versions:
    • Creating versions should be possible without the current restrictions; currently it's only possible to create a new version e.g. on already-published content.
    • We may have to review how/when to allow version deletion, e.g. if a version is created by accident. Currently versions cannot be deleted.
    • See also Relax editing metadata on published/posted materials #10263

Update (2019)

See #4860 (comment)

Original Comment

Publications should introduce three new data fields: publicationSummary and publicationDateType.

• Discuss what types of publications we should support and if there is an existing third-party specification we want to follow. The obvious examples for us to start are preprint and publication. But if there's a standard to follow, that'd be great. This should be a controlled list. Conclusion: JATS uses publicationDateType and there is no need for a separate publicationType.
• Add a select field for the publicationDateType from the list supported in JATS: https://jats.nlm.nih.gov/archiving/tag-library/1.1d1/n-u252.html
• Add a text input field for publicationSummary that allows someone to enter a short description of the version. Think of this like a commit message.
• Use the publicationDateType and publicationSummary in the publication UI, to identify the versions in the version dropdown.
• Add the publicationDateType and publicationSummary to the reader interface to identify versions.

[NateWr]

@ajnyga on possible publicationTypes:

Crossref supports preprints and articles, JATS has this, but no defined set of values https://jats.nlm.nih.gov/archiving/tag-library/0.4/n-ugk2.html
then there is this: http://vocabularies.coar-repositories.org/documentation/version_types/
note that it does not have a value called "preprint", in OJS context preprint would be "submitted version"
but the COAR vocabulary is probably the most detailed

I think we should definitely look at what Crossref supports and consider following them as a standard since it links up with DOIs and other key things we're working with.

[withanage]

Hi @NateWr ,
I added the comments and thoughts between the lines.

Discuss what types of publications we should support and if there is an existing third-party specification we want to follow. The obvious examples for us to start are preprint and publication. But if there's a standard to follow, that'd be great. This should be a controlled list.

Add a select field for the publicationType from the options we settle on above in the publication UI, as well as adding validation rules for them.

In Onix they have publishing status, which only addresses the status related to selling.

https://onix-codelists.io/codelist/64

My suggestion would be to consider the best practise guide-lines from here.

https://jats.nlm.nih.gov/extensions/bits/tag-library/2.0/attribute/publication-format.html

Add a select field for the publicationDateType from the list supported in JATS: https://jats.nlm.nih.gov/archiving/tag-library/1.1d1/n-u252.html

yes, this list is also the same for books, therefore I also think this is the best possible.
https://jats.nlm.nih.gov/extensions/bits/tag-library/2.0/attribute/date-type.html

Add a text input field for publicationSummary that allows someone to enter a short description of the version. Think of this like a commit message.

Sure a short description is very nice to have. I also would prefer the message in multilingual.

JATS/BITS has a event description concept for that.
https://jats.nlm.nih.gov/extensions/bits/tag-library/2.0/element/event.html

<pub-history>
<event>
<event-desc>pre-conference proceedings</event-desc>
<date iso-8601-date="2013-07" date-type="pub" 
publication-format="online">
<month>July</month><year>2013</year></date>
</event>
<event>
<event-desc>post-conference proceedings</event-desc>
<date iso-8601-date="2013-10" date-type="pub" 
publication-format="online">
<month>October</month><year>2013</year></date>
</event>
</pub-history>

Use the publicationType and publicationSummary in the publication UI, to identify the versions in the version dropdown.

Sure, I agree.

Add the publicationType and publicationSummary to the reader interface to identify versions.

Only addtion here is, may be there can be a future requirement to display date alongside the type and summary or only type and date without summary.

[NateWr]

Thanks @withanage!

It doesn't look like Onix or the BITS publication-format is a good fit for this (though maybe properties to add to OMP).

I am looking for something that specifies the version itself -- ideally something like preprint, publication, revision, etc. Maybe the publicationDateType is the appropriate place for this, and we should abandon publicationType until we've found a suitable standard.

Sure a short description is very nice to have. I also would prefer the message in multilingual.

✔️

a future requirement to display date alongside the type and summary or only type and date without summary.

Yeah, this will likely be something changed on a theme-by-theme basis. And if we remove publicationType then using the publication date, publicationDateType and summary will be useful.

[withanage]

I am looking for something that specifies the version itself -- ideally something like preprint, publication, revision, etc. Maybe the publicationDateType is the appropriate place for this, and we should abandon publicationType until we've found a suitable standard.

Yes, I agree publicationDateType with the chronological order can cover the revisions for the submissions.

Submission Workflow

accepted, corrected, received, resubmitted , retracted, rev-request, rev-recd with date and summary.

https://jats.nlm.nih.gov/archiving/tag-library/1.2/attribute/date-type.html

Galley

pub , Preprint

The names are used in very different ways by large publication houses.

preprint = "Advance online publication"

https://www.nature.com/nature-research/for-authors/publish#about-aop

One thing which can also be a long-term requirement is , how to associate a specific workflow version with a galley version? Or even search for a specific published version of a submission workflow file. I think sooner or later, this will also come.

[NateWr]

One thing which can also be a long-term requirement is , how to associate a specific workflow version with a galley version? Or even search for a specific published version of a submission workflow file. I think sooner or later, this will also come.

Hopefully later... 😂 We don't have any way to make this association with the implementation we're pursuing now, and to do so would require a major intervention into the workflow. For now, we've managed to separate out versioning from the workflow in order to limit our refactoring work.

[NateWr]

COAR released a new version July, 2019: https://www.coar-repositories.org/activities/repository-interoperability/coar-vocabularies/deliverables/

[NateWr]

It looks like the only meaningful entries for publicationDateType at this time are preprint, pub and corrected. Since we won't support preprints in 3.2, that leaves pub (the original publication date) and corrected (all other versions).

This doesn't provide us with much information, and the data would probably be better handled automatically based on a journal's publishing workflow, rather than making editors set it for each version (and likely set it incorrectly). I'm going to leave it out for now. We can revisit this down the road if things change.

I'm also going to put publicationSummary on the backlog for now, so it won't be included with v3.2. It would be nice to have a summary of revisions, but whether to make it a text field or a tinymce field is up for debate. And in either case I think we can ship without this and add it as requested.

[alexxxmendonca]

When dealing with preprints, two (ideally three) statuses should be taken into account:

• This preprint has not been published.
• This preprint has been published (+ option to add DOI + publication title)

Ideally, one third option would sit between those two mentioned above, to be used for cases where the preprint has been accepted in a journal but not yet published (also known as "postprint"):

• This preprint has been accepted by a journal but not yet published

SRRN preprint server indicates the name of the journal where it's supposed to soon be published: https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3690578

"Latin American Research Review, Forthcoming"

Preprint authors as well as preprint server managers should be able to change these statuses. Such changes should appear immediately at the preprint landing page as labels: