Consider adding CalVer as an alternative to SemVer

[dcmiddle]

The badge criteria recommends SemVer exclusively. Perhaps any structured and well reviewed versioning scheme satisfies the security best practices objective. In particular CalVer is used by Ubuntu and other recognizable projects.

https://calver.org/ In particular see https://calver.org/#when-to-use-calver

For purposes of healthy discussion here are some counter-arguments:

• More suggestions are less concise. -- More suggestions and more to read makes the process more difficult without proportionate benefit.
• CalVer may be most applicable to large projects and presumably most projects are small.

[david-a-wheeler]

It's a really interesting idea, and I can see some advantages.

There's another counter-argument: CalVer doesn't handle multiple branches well, e.g., 2.X vs. 3.X branches. Thoughts?

[dcmiddle]

It's a really interesting idea, and I can see some advantages.

There's another counter-argument: CalVer doesn't handle multiple branches well, e.g., 2.X vs. 3.X branches. Thoughts?

I'm not sure what you mean but let's see if this is helpful... CalVer uses Major:Minor:Micro e.g. Year:Month:Patch. So there shouldn't be any issue with version controlling security fixes if that is the concern. For example, Ubuntu LTS has fixes that get backported into older releases. Like right now 20.04 is the latest Long Term Support (LTS) release but the 2016 release has backported fixes and is listed right now as 16.04.7.

[david-a-wheeler]

It is helpful! I guess you're right, it doesn't have problems handling branches.

The CalVer page has an interesting description of when to use CalVer:

• Does your project feature a large or constantly-changing scope?
  • Large systems and frameworks, like Ubuntu and Twisted.
  • Amorphous sets of utilities, like Boltons.
• Is your project time-sensitive in any way? Do other external changes drive new project releases?
  • Business requirements, such as Ubuntu's focus on support schedules.
  • Security updates, such as certifi's need to update certificates.
  • Political shifts, such as pytz's handling of timezone changes.

I can see adding this as a legitimate alternative. I think the next step is to write proposed text & distribute it around for comment. I can do that unless you'd prefer to take first crack at it.

[david-a-wheeler]

CalVer works if the project includes a "micro" value (as many do). Then, if there's a branch off an older version, it's easy to determine what's going on. However, CalVer doesn't strictly require a micro value. I think if we suggest that the CalVer include a micro value then it'd also be fine. Obviously we'll need to get a larger review, but the first step is to develop proposed changed text.

===

Here's the current text of criterion version_semver:

description: It is SUGGESTED that the Semantic Versioning (SemVer) format be used for releases.

details: Other version numbering schemes, such as commit IDs (such as git commit id or mercurial changeset id) or date-based schemes like YYYYMMDD, MAY be used as version numbers, since they are unique. Some alternatives can cause problems, because users may not be able to easily determine if they are up-to-date. SemVer may be less helpful for identifying software releases if all recipients only run the latest version (e.g., it is the code for a single website or internet service that is constantly updated via continuous delivery).

Here's some proposed alternative text to SUGGEST either SemVer or CalVer:

description: It is SUGGESTED that the Semantic Versioning (SemVer) or Calendar Versioning (CalVer) format be used for releases. It is SUGGESTED that those who use CalVer include a micro level value.

details: Projects should generally prefer whatever format is expected by their users, e.g., because it is the normal format used by their ecosystem. Many ecosystems prefer SemVer, while CalVer tends to be used for projects that are large, have a constantly-changing scope, or are time-sensitive. It is SUGGESTED that those who use CalVer include a micro level value, because this format support simultaneously-maintained branches when necessary. Other version numbering schemes, such as commit IDs (such as git commit id or mercurial changeset id), MAY be used as version numbers, since they are unique. However, some alternatives (such as commit IDs) can cause problems as release identifiers, because users may not be able to easily determine if they are up-to-date. Formats may be unimportant for identifying software releases if all recipients only run the latest version (e.g., it is the code for a single website or internet service that is constantly updated via continuous delivery).

Thoughts?

[david-a-wheeler]

P.S. Identifying versions is important for security, because we want people to quickly update if they have a vulnerable version... which means that we need to help users identify (1) the version they're using and (2) the version they should be using.

[dlorenc]

I think it makes sense to expand the allowed versioning. Kubernetes and most things in the CNCF are too large to follow semver, for example.

CalVer is nice, but none of these are perfect. What about just requiring projects to use a well-documented versioning scheme, with a few of these as suggestions.

[david-a-wheeler]

What about just requiring projects to use a well-documented versioning scheme, with a few of these as suggestions

That's already the case; this particular criterion is just SUGGESTed. The current text suggests only SemVer.

There had been earlier discussion about using calendar dates as version numbering, as clearly some projects do that. The problem has been that with dates there was no way to clearly distinguish branches when they live simultaneously, which does happen. CalVer includes an option (micro levels) that eliminates that historical problem of dates as version ids. E.g., 2020.9.4 is different from 2021.1.1, even if they're both "current" versions.

[kwwall]

I think SemVer should be the recommendation for SDKs and APIs, because they Major # is important in determining backwards compatibility of the clients of those SDKs or APIs. Using CalVer does not seem to make that as obvious. In addition, for SDKs and APIs, it seems that CalVer is somewhat redundant with the release date (or at least discernible from that).

[dlorenc]

Versioning schemes are definitely a big topic to bikeshed on.

The problem has been that with dates there was no way to clearly distinguish branches when they live simultaneously, which does happen

Yup, no scheme is perfect. Some seem to fit some types of projects better than others, though.

I think SemVer should be the recommendation for SDKs and APIs,

Maybe we could build on this and provide concrete recommendations of schemes based on the type of project?

One area semver falls apart IMO is when projects get larger. This is a case of https://xkcd.com/1172/. Without a very very very well defined API surface, every change can be considered a breaking change to someone, so the semantics around "breaking" begin to lose meaning. The "correct" way according to the semver spec is to just bump the major version on each release in that case, which works but takes away all semantic meaning of the versioning spec.

Shameless plug for my personal favorite versioning scheme, RealVer :)

[david-a-wheeler]

Like many of the best jokes, RealVer is disturbingly close to the truth :-).

The goal of SUGGESTed criteria is to encourage behavior that's usually the right thing to do, but for which there are so many exceptions that it's not worth even asking for an explanation as to why something different was done. If nothing else, it's hard to change a version numbering system once set.

The proposed text already notes that CalVer tends to be preferred as projects get large; we could add "include a large number of dependencies". We could also note that SemVer tends to be preferred for SDKs and APIs.

So I tweaked the text to hopefully cover these discussions, and while I was at it, I tried to simplify the details text in general. How about this?

====

Proposed alternative text to SUGGEST either SemVer or CalVer:

description: It is SUGGESTED that the Semantic Versioning (SemVer) or Calendar Versioning (CalVer) version numbering format be used for releases. It is SUGGESTED that those who use CalVer include a micro level value.

details: Projects should generally prefer whatever format is expected by their users, e.g., because it is the normal format used by their ecosystem. Many ecosystems prefer SemVer, and SemVer is generally preferred for application programmer interfaces (APIs) and software development kits (SDKs). CalVer tends to be used for projects that are large, have an unusually large number of independently-developed dependencies, have a constantly-changing scope, or are time-sensitive. It is SUGGESTED that those who use CalVer include a micro level value, because including a micro level supports simultaneously-maintained branches when that is necessary. Other version numbering formats MAY be used as version numbers, including git commit IDs or mercurial changeset IDs, as long as they uniquely identify versions. However, some alternatives (such as git commit IDs) can cause problems as release identifiers, because users may not be able to easily determine if they are up-to-date. The version ID format may be unimportant for identifying software releases if all recipients only run the latest version (e.g., it is the code for a single website or internet service that is constantly updated via continuous delivery).

Thoughts?

[kwwall]

+1 - Works for me.