Criteria for versioning

[wdduncan]

On the MIXS-RDF call today, questions about versioning came up.

If we adopt semantic versioning (i.e. Major.Minor.Patch), we need to have clear criteria on when each number is updated.

So, starting this issue for a place to discuss this.

cc @lschriml @ramonawalls @only1chunts @turbomam @cmungall

[wdduncan]

Some notes from the 2021-11-22 regarding major/minor versions:

What is a major and minor version
Major: breaks backward compatibility (i.e., MIxS 5 and 6 were major)

• Breaking compatibility:
• Changes in definitions?
• Removal of terms?
• Merging of terms?

Minor release:

• Addition a new package or checklist
• New terms
• Not only INSDC want annual releases - others align with INSDC
• We should separate the semantic versioning from the annual release.

[cmungall]

I think there are advantages to a simple system where the major number increments every year or so

I would like to see formal versioning of pre-release aretfacts, e.g we should be working on 7.0.0-alpha now

[only1chunts]

@wdduncan I like your list of what classes as major or minor, but does it need to be more granular than that? e.g. a change to a definition might be something as small as a misspelled word being corrected, in which case it doesn't break backwards compatibility, so could be a minor release. We cant list all the possible changes that might occur so there will be a degree of fuzzyness to the system.
On the other hand, if we stick with the simplistic ~annual release being the big number change with anything in-between being a dot change, it makes it easier for the non-technical people to understand and for partners to know when they are not keeping up with their annual updates. The dot changes will allow users that want to keep up to the minute to do so.
@cmungall , I'm not sure I understand what you mean by pre-release artifacts?

[wdduncan]

@only1chunts You raise good points. I suppose the answer comes down to what we want out of having a versioning system.

• When incrementing the version number, do we care to communicate the new version is not compatible with the previous version?
• Do new versions necessary contain new terms/packages? Suppose that a version only contains a bunch of typo fixes found version 7. Do you want to release this as version 8?
• If we adopt incremental releases as packages are released (e.g. 6.1, 6.2, etc.), when do we decide to increment the major number and what does that major number mean? For example, suppose for version 6 that we add 5 packages during the year, resulting in version 6.5 by year's end. Do we make a release 7.0 that is the same as 6.5? If so, how do we communicate to the community that 6.5 is that same as 7.0?

I think changes to wording that don't affect meaning would be appropriate for incrementing the patch number (e.g., 7.0.0 -> fix some minor typo -> 7.0.1).

Anyway, sorry to only raise questions here. We can, of course, stick with current practice of just making new releases after some threshold of changes have been made during the year. The benefit of creating rules/criteria for versioning may not be worth the effort. But, perhaps, we should at least pause and think about it for a moment?

[ramonawalls]

I think a major release involves changes to the core, and that we should stick with the practice of making major releases approximately once a year. I like Bill's suggestion that changes like fixing a typo would be a patch number (e.g., 6.0.1).

Throughout the year, we can allow the addition of new packages and checklists, and those would be minor release. If the new package/checklist requires a change to core or a change to a term that is shared across many packages, that change will have to wait until the next major release, but new package/checklist specific terms could be added to a minor release.

Following Bill's example, if we have add five new packages between version 6 and 7, to end the year with 6.5, we would then release 7.0, but it would not be the same as 6.5, because their would be changes to the core terms and to any terms that are shared across multiple packages. Based on past experience, it is very unlikely that we would get through a year without changing the core. If, perchance, we did, then our annual release would just be 6.5.

Another complication is that people want to be able to mint new terms throughout the year, which may be part of core. I suggest we can give those terms identifiers and publish them in the editor's (non-stable) version of MIxS, but that they would not be officially released until the major release. With github, we could keep our (as yet non-existant) validators up to date in the repo if someone wants to use them provisionally, but the "official" validator would be part of the tagged release that comes out each year. For this to work, we probably need to validate packages/checklists separately from core, which makes sense to me anyway.

[wdduncan]

This sounds reasonable to me.

[ramonawalls]

We need to resolve what we mean by "core" (issue #77) before we can define this exactly.

Regardless, adding a new term is a minor release. Changing a term is considered breaking and has to happen in a major release. Typos and similar will be a patch.

[ramonawalls]

This issue is being covered in this document: https://github.com/GenomicsStandardsConsortium/mixs/blob/606-mixs-editing-workflow-and-policy/src/docs/policy.md and issue #606 . Closing.