Semantic vs calendar versioning?

[effigies]

We discussed yesterday how our current development workflow doesn't really follow semantic versioning. The current plan is to have a 2.0 release in early 2020, but there aren't breaking changes that necessarily justify it, so much as a sense that a good deal of progress has been made.

I suggest that we move to a calver system, such as pip uses, which is short year + minor version + patch (YY.MINOR.MICRO in calver parlance). This would reflect fMRIPrep's nature as an evolving workflow and not impose any artificial incentive for "big change" releases. It would also let us quickly see just how out-of-date someone's fMRIPrep version is.

I would propose that we take YY.MINOR.MICRO wholesale, and make the first significant release of 2020 20.0.0.

I would then follow these conventions:

1. The default release is a minor version release. The presumption will be that working directories cannot be reused between minor releases.
2. Micro releases can only include bug fixes that can be reuse working directories. Failing interfaces fit in here. always_run interfaces that were succeeding but producing bad outputs can also be fixed here. (Arguments can probably be made for occasionally specifying a node or sub-workflow working directory to delete, but if we find ourselves doing this a lot, it's probably a bad sign.)

I would not impose a particular cadence, such as monthly releases.

---

The above is a combination of my view and a recollection of the overall gist of a discussion. This should be taken as my own position, and not necessarily that of the core developers.

[oesteban]

I like YY.MINOR.MICRO for fMRIPrep.

[dorianps]

Perhaps a naive question: how would someone know that 19.5.2 is compatible with 20.5.3?

[effigies]

What do you mean compatible?

[dorianps]

Referring to this:

The default release is a minor version release. The presumption will be that working directories cannot be reused between minor releases.

If the major changes are in the second number, then it means the user will need to focus on that number, instead of the first, as the number bearing the weight (i.e., trying to image how a change like 1.4 to 1.5 currently will be reflected in the new versioning).

[dorianps]

In other words, if the two concepts (time and amount of changes) need to be merged into a single version, I would suggest the two are made as much distinguishable as possible. In this case, at least go for long year inistead short (2020.5.2) because the short year looks very much like a semantic version (20.5.2).

[dorianps]

And then, again, it would be a question of how does someone know the amount of changes between 2019.10.2 and 2020.1.5. Anyway, just my thoughts, since this is an open discussion.

[effigies]

Ah, to be clear, we won't go from something like 19.3.1 to 20.3.2, where you would be expected to see that the minor version numbers are the same. If it's a compatible release in the sense you describe, the next would be 19.3.2, even if it occurs in 2020. It would just be that the next minor release would be 20.0.0.

I'm not personally enamored of the 2020.X.Y over 20.X.Y, but I'm okay being overruled on that one, if the general consensus is that will be easier to understand.

I agree that the level of change between 20.3.1 or 20.5.2 and 21.0.0 is going to be hard to estimate. But frankly, it's currently hard to estimate how different 1.2.0 and 1.5.0 are. Some minor versions have represented a few changes, some a lot. At some point you need to check the changelog. And at least with calver, we'll be able to see that you're running something from this year.

[oesteban]

@dorianps perhaps it is more about how we update the changelog (https://fmriprep.readthedocs.io/en/latest/changes.html) to make the list of changes more interpretable (at this point the changes are listed, but you really need to be deep in the weeds to understand their implications).

There is one thing: with the versioning system change we will try (and hopefully succeed) to be more rigorous. In other words, this far we've been "kind of" semantic but with lots of exceptions (mostly, to be honest, derived from sloppiness and scheduling on my end). After the change, we'll stick with the premise that the minor means "it's not backward compatible" and patch means "backward compatible". The major will help us quickly identify how big the changes could be.

To preempt the problem of the new calendar year pushing some seemingly API-breaking changes, we could force two releases being generated the last day of the year and the first day of the year:

21.0.0 (released on Jan 1, 2021) would be backward compatible with 20.5.150 (minor release forced on Dec 31, 2020).

I don't see any advantage in seeing the full year first either.

[dorianps]

Ok, thanks for explaining, I get where you are going with this. I am personally not used with recognizing versions like this (i.e., 21.0.0 being same as 20.5.150) but I guess you know better what you want to achieve in the long run. My alternative suggestion would be not to bump to 21.0.0 unless there is a substantial change. That is, if nothing happens in 2021 versions should go up to 20.5.1150, and only if you want to push the 5 up by one you can go to 21.0.0 or 22.0.0 (depending on the year that happens). This is because, again, resetting the 2nd.3rd numbers because the year changes means that the temporal concept is fully impacting the semantic concept for no other reason than time passing.

[effigies]

That is, if nothing happens in 2021 versions should go up to 20.5.1150, and only if you want to push the 5 up by one you can go to 21.0.0 or 22.0.0 (depending on the year that happens)

Yes, this is what I mean. For instance, we just released 1.5.5, and if there's another bug fix, it will be 1.5.6, but the next release with significant changes will be 20.0.0.

That is, assuming this is settled. I see three 👍s on the initial post, and I think @dorianps's last post sounds consistent with what I imagined.

Does this sound good to everyone?