Be clear and opinionated about what CalVer is and is not

[broofa]

'Landed here while googling for "date-based semver". I read / scanned the whole document. When I got to the bottom section, "When to Use CalVer", I found myself wondering if I'd missed something.

Like, what is CalVer, exactly???

calver.org summarizes some projects that use date-based version schemes and discusses some common fields and practices in fairly broad terms, but no attempt is made to describe any one, preferred versioning system. And even the examples provided are at times confusing ("YYYY.MM.DD_MICRO" doens't use "point-separated numbers")

In short, CalVer seems little more than a notation for describing [date-based] version strings. But that doesn't seem all that useful.

Questions it doesn't answer:

• How can I identify a CalVer string?
• What is and is not a valid CalVer string?
• What process should be used to generate a CalVer string?
• Is it expected that CalVer strings be parsable to extract the timestamp? (Not a given, btw.)
• What are the requirements for a CalVer string parser?

(BTW, if the answer to that last question starts with, "first you need to know the format description..." then this document hasn't done it's job.)

In short, what i'm suggesting is that rather than being a hand-wavy collection of possible date-based formats, CalVer should springboard off the research that's already been done, and define a single, canonical format that meets the needs of the community moving forward rather than focusing on legacy versioning systems.

---

Aside: I think CalVer would benefit by being explicit about the fact SemVer is a well-established thing, and that CalVer strings MUST be SemVer compliant. [Edit: Upon further consideration, I've concluded this is just a terrible idea. SemVer and CalVer are just too at odds semantically for this to be viable.]

[broofa]

For example... Is it required that dates and times MUST be in UTC? You say it's "assumed", but that's not the same as a mandate. And any ambiguity in this regard is certain to cause confusion.

[markrwilliams]

I have some thoughts, in my capacity as a contributor to calver.org and a (less-active) Twisted maintainer, that might be helpful.

Like, what is CalVer, exactly???
...
In short, CalVer seems little more than a notation for describing [date-based] version strings.

That's exactly right. It's a description of versioning, not a prescription for it, with an emphasis on human instead of machine comprehension. Mahmoud wrote a nice overview of this methodology and a defense of CalVer that's linked to from calver.org.

But that doesn't seem all that useful.

Naturally I disagree! In the case of Twisted, we wanted a partial lexicographic order on versions (it couldn't be total because once upon a time Twisted used something like Semantic Versioning) so that installers could identify newer releases for upgrades, and we wanted to make it clear when an upgrade might break your code due to our time-based compatibility policy.

Twisted itself contains a bunch of different things, like mail servers and web servers, that each have different APIs protected by different compatibility timelines, and so would each require their own version in a more granular versioning scheme. That alone made Semantic Versioning untenable. But really, compatibility is a negotiation, not a statement; even with high test coverage, it's easy to miss changes that break your users, which is why projects like cryptography test important downstream projects on every release. That of course isn't a panacea because of its limited focus. Neither is CalVer - however, the point of CalVer is to tell the humans using your project something, which worked well for Twisted in concert with its compatibility policy.

Implicit in this discussion is my assumption that a human being has to review each and every upgrade. I think that's roughly true! You can have something bump your dependencies on a regular cadence, but it's up to you to make sure that those updates are acceptable. Sometimes that's a unit test suite passing, sometimes that's a release candidate, sometimes it's a deployment to a test environment, sometimes that's a person reading changelogs, etc. A rigorous spec for CalVer wouldn't make any of that easier, and it wouldn't communicate anything more to its primary consumers: the people who maintain and use the versioned software.

Questions it doesn't answer:
How can I identify a CalVer string?
You don't - you learn out-of-band that a project uses CalVer. You typically don't worry, though, because releases are ordered lexicographically, so upgrades work for tools that understand lexicographical version ordering, like pip.

What is and is not a valid CalVer string?
If it doesn't communicate something about a date related to the project's maintenance, it's not CalVer.

What process should be used to generate a CalVer string?
It should include a date relevant to the project's maintenance (e.g. when a release happens), and it should be structured in a way that the relevant installer knows that it's a newer version.

Is it expected that CalVer strings be parsable to extract the timestamp? (Not a given, btw.)
Probably not.

What are the requirements for a CalVer string parser?
Given the above, I wouldn't bother with a CalVer string parser.

You might find this subset of CalVer more useful for your use case, which includes a section with an interpretation of RFC 2119's terminology:

https://chronver.org/

Is it required that dates and times MUST be in UTC?

Unfortunately ChronVer doesn't specify this! I think it might be good to ask its maintainer(s) about that, but I wonder if they'd respond that constraint is merely that the same timezone is used for all releases?

[broofa]

@markrwilliams Thanks for the thoughtful response. Rather than get into a lengthy debate over the merits of date-based versioning vs. semantic versioning, let me ask, "what value does CalVer add to Twisted?"

I'm not talking about the general idea of date-based versioning. I'm talking about CalVer, specifically, which claims to be "a versioning convention based on your project's release calendar." It's literally the first line on the project home page.

So how is Twisted using this "convention"? What benefits is it providing?

From where I sit the answer is pretty clearly, "it's not." Oh, sure, twisted is using date-based versioning and benefiting from that, but the fact "calver" is only mentioned once - and only then to note one of its shortcomings - would seem to indicate CalVer™ has little to do with that.

I suspect the reason for that is that CalVer, in it's current form, doesn't really offer much. Contrary to what the home page claims, CalVer isn't actually a convention. It's a convention for describing conventions, and a rather amorphous one at that. For example, twisted's format is listed as "YY.MM.MICRO"... but calver only defines "micro" as the third field in the string without actually saying what's in the field.

That's not all that useful.

[mahmoud]

Hey @broofa! @markrwilliams beat me to most of what I'd say, so I think the core clarification is that: Twisted (and all projects listed on calver.org) predate CalVer. The purpose calver.org serves is to show that there's a useful alternative to SemVer that applies across a wide range of projects and domains. It also gives maintainers a place they can redirect devs who are new to the concept of date-based versions. Twisted in particular has their documented calendar-based compatibility policies typical of mature projects, so they get extra benefits from CalVer usage.

So, you're right that CalVer is a convention for describing individual-project conventions. FWIW, SemVer is, too, for all the effort it puts into pretending to be a spec. SemVer is more amorphous, specifically because the subjective term "breaking" is reinterpreted every time a project cuts a new version. Many (most?) teams hesitate in getting their major version off 0 or letting the version going too high, because the numbers become meaningless. CalVer doesn't have these problems. For more details on the topic, I've written this.

calver.org does presume familiarity with the MAJOR/MINOR/MICRO/PATCH that predate any of these branded versioning conventions. It may make sense to include quick definitions, if you think that would improve readability?

[mahmoud]

Good convo. Seems a shame to simply close the issue, so I've activated GitHub Discussions and am going to let it live on over there.