
CalVer: Calendar Versioning - tosh
https://calver.org/
======
eqvinox
This comes crashing down in a nice mudslide the exact moment you start
maintaining an older stable release for fixes while also progressing on a
newer version. If anything, date codes are useful as later version number
component, e.g. 4.1.0.191220.

Also, the "When to use" section is getting things quite wrong:

    
    
      Does your project feature a large or constantly-changing scope?
        Large systems and frameworks, like Ubuntu and Twisted.
        Amorphous sets of utilities, like Boltons.
    

Wrong question - relevant is: "is your project the top end of the dependency
chain?"

    
    
      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.
    

And both of these are actually made much harder by calendaric versioning.
Administrators are already reluctant to update software for fear of breaking
things. SemVer gives extremely useful information here to establish how
"dangerous" and update might be. With date code versions, the admin is forced
to dig through change logs, which costs time they probably don't have, so
they'll just not update.

~~~
skissane
> SemVer gives extremely useful information here to establish how "dangerous"
> and update might be.

I'm doubtful about how useful the information SemVer gives really is. Someone
can make massive changes to a package, rewrite half of it from scratch, add
huge new features, completely redesign how parts of it are implemented, but if
they don't making any breaking API changes the first version segment doesn't
increment. On the other hand, someone removes some obscure feature which
nobody ever used anyway, and that causes the first version segment to
increment. The administrator should be much more worried about the first
change than the second, but SemVer misleads them into being more worried about
the second than the first.

~~~
SahAssar
SemVer is about the public API, it says nothing about test-coverage, internal
changes or transient dependencies.

The point of SemVer is to answer "if I trust the authors of this library to be
as good or better than me at writing libraries, is it safe to upgrade?". The
moment you don't trust the authors of the library to be as good or better than
you it sorta breaks apart as a covenant, but it will still show the intent of
the author.

So SemVer has problems, but CalVer just shows "I tagged a release at a date".

IMO badly practiced SemVer is better than perfect CalVer simply because I can
open an issue of fix something that was broken because of SemVer, but with
CalVer I need to live with any breakages regardless of if they were
intentional or not.

------
plainOldText
I find calendar versioning virtually useless. It reveals the freshness of
one's project over much more important information such as maturity, as
revealed by semantic versioning.

Imagine researching some libraries and having to decide over which one to use,
say _LibA v2020.01.06_ vs _LibB 2019.12.31_. These versions tell you nothing
about the projects except their release dates.

On the other hand, semantic versioning (when not abused) – say _LibA v3.0.1_
vs _LibB 1.0.0_ – reveals something useful, such as, that LibA has undergone
three major revisions, so perhaps it is much more mature than LibB.

Perhaps the calendar versioning works well with already mature and famous
projects – e.g. _Ubuntu 18.04_ , etc – but for smaller projects I don't think
it's such a good idea.

 _Comment v1.0.4-20jan06_

~~~
elsurudo
Not sure if you should rely on SemVer for maturity estimates either, though. I
guess it can be one signal, but I wouldn't say a very useful one.

~~~
itake
what would be a more reliable way to know?

~~~
codetrotter
Look at the following:

\- Number of commits.

\- Number of open issues.

\- Number of closed issues.

\- How they respond to issues.

\- Are the commit messages descriptive?

\- Is the codebase a mess or does it look reasonable?

------
timeattack
I'm using similar versioning for pre-build packages, but it's extended with
commit information to 1:1 mapping to the source tree:

    
    
      local date=$(git log -1 --format="%cd" --date=short | sed s/-//g)
      local count=$(git rev-list --count HEAD)
      local commit=$(git rev-parse --short HEAD)
      echo "$date.${count}_$commit"
    

Example result:

    
    
      20191121.68_84f90ff
    

It provides user about general information about when program was updated
along with specific information for developer for bug reporting. Also, it
allows intraday releases.

~~~
emptysea
FYI, using `local foo=$(some-command)` does not actually make the variable
local.

    
    
        main() {
          local count=$(git rev-list --count HEAD)
          echo $count
          foo
        }
        
        
        foo() {
          echo $count
        }
        
        main
    
    

prints:

2282 2282

~~~
minitech
Sure it does, that’s just how locals work (in bash and similar). Try printing
it after `main` with and then without `local`.

~~~
emptysea
Ah my mistake

Anyways there are some more subtle caveats discussed in this blogpost I was
trying to remember:

[https://jmmv.dev/2018/03/shell-readability-
local.html](https://jmmv.dev/2018/03/shell-readability-local.html)

------
TheCraiggers
I thought this was a new team calendar that was version controlled when I
first read the headline. And now I want that.

~~~
tasn
I also wish all of my data was version controlled, which is why when I created
EteSync[1] I made sure to include a full change history. Check it out, I think
it's exactly what you're looking for, and it's fully open source, so you can
host in on-site if your company requires that.

[https://www.etesync.com](https://www.etesync.com)

~~~
aidenn0
Can that do shared calendars? (I know that's technically challenging with ETE
encryption). If it does, I will drop my self-hosted davical for it in a
heartbeat.

~~~
kalmi10
I found this in the FAQ:

If I want to share a calendar with my spouse, do I need to get two
subscriptions? No. You can just create a normal subscription for yourself, and
an "Associate" subscription for your spouse. Then share the calendar with the
second account, and that's it. However, Associate accounts can't create their
own calendars. So in order to have a personal calendar (that you can't see),
your spouse will have to get a normal subscription too.

------
NaNtales
One use case for this that comes to mind is for patching multiple major
versions with a particular fix.

For example, you might release a hotfix patch today that fixes a bug in all
major versions of your software. Using calendar versioning as a patch number
would give something like

\- 3.4.20200106

\- 2.1.20200106

\- 1.5.20200106

making it very easy to tell whether a particular version includes todays fix
or not.

------
sakisv
I find this absolutely useless for libraries.

For things like Ubuntu yes, it makes sense because you wouldn't just run a
command to upgrade your os.

However, your code you usually has a bunch of libraries that depends on. When
I upgrade a library I don't care _when_ the new version came out, all I care
is that doesn't have breaking changes.

With semver I can get this information at a glance, calver on the other hand
just says "newer version".

As others have mentioned, some combination of both approaches might give an
extra data point for "freshness" especially if you're managing multiple
versions, but even then what's wrong with just bumping the minor/patch?

------
RKearney
> YY - Short year - 6, 16, 106

> [...]

> Note that traditional, incremented version numbers are 0-based, whereas date
> segments are 1-based, and the short and zero-padded years are relative to
> the year 2000.

Y3K here we come!

~~~
mfer
You don't need to wait for Y3k. 21xx is enough to cause duplication.

There is software still running from over 50 years ago. I'd imagine new
releases have come out. But, this may be a legit problem some day.

~~~
Sean1708
The upside being that releasing a new version with a different version scheme
isn't a time-sensitive task, the old version isn't going to stop working just
because the new version number wouldn't be valid.

~~~
0xffff2
Changing versioning schemes comes with its own set of problems. There is
rather famously no "Windows 9" because enough people detected Windows 95/98
with the equivalent of a regex looking for "Windows 9*" that Microsoft thought
it might be a problem.

~~~
Sean1708
My point isn't that it has no downsides, my point is that it would be a far
less pressing issue than Y2K was.

------
regularfry
I've done something similar to this in the past, only simpler: "YYYYMMDDXX"
where XX is an incrementing index of today's releases.

It works well where you've got no commitment or requirement to release patches
of old versions rather than roll forward. In my experience, that covers most
internal software, where semver is overkill.

~~~
lioeters
I've used the same format as you mentioned, usually for non-public-facing
modules. Sometimes it starts with "YYYYMMDD", then "YYYYMMDD.XX" if needed.

Every version potentially breaks backward compatibility, regardless of
versioning standard (semver, calver, or anything else). It's the
responsibility of the module consumer to have tests and ensure its own
functioning.

I do find semantic versioning useful for public-facing modules/interfaces, to
indicate (or infer from the consumer side) the intended compatibility. In
practice, though, sometimes patch versions break things, or major version
upgrades work fine without any changes. So the consumer still needs to be
responsible for ensuring compatibility - not much different than calendar
versioning.

~~~
regularfry
Yeah, that was my realisation. Semver ends up being a lie often enough, and
back-ported patches happen rarely enough, that it ends up being engineering
theatre more often than not.

------
Deukhoofd
You should probably look at updating your TLS. TLS 1.0 will be deprecated in 2
months.

~~~
chrismorgan
TLS 1.0 won’t be _deprecated_ in two months’ time, it’s being _removed_ in two
months’ time (from at least Firefox, Chrome and Safari; for IE and Edge
Microsoft have just said the first half of the year). It’s already deprecated,
has been for yonks.

~~~
mhashemi
You're quite right, and this site is being migrated this week. I was going to
do it this morning, but there was a traffic spike for some reason? :)

~~~
mhashemi
All done, thanks again for looking out!

------
SamWhited
For some projects I like the idea of calendar based versioning, sadly I mostly
write Go and they've decided that anything but semver isn't allowed if you
want to use the new packaging standard, Go Modules :(

~~~
mfer
Funny thing is, the previous tools for Go and tools in other languages tell
you SemVer but you have enough control that you can use CalVer if you like.

------
flixic
A good 30 minute podcast discussing this topic is Episode #164 "Meaningless
Version Numbers" of Under The Radar podcast with Marco Arment and _David
Smith.

During this episode Marco explains his decision to switch to YYYY.MINOR.MICRO
scheme for Overcast, his podcast player.

[https://www.relay.fm/radar/164](https://www.relay.fm/radar/164)

------
awoods187
At Cockroach Labs we switched to Calver covered in this thread
[https://news.ycombinator.com/item?id=19658969](https://news.ycombinator.com/item?id=19658969)

------
wodenokoto
I would have expected D to be short day (1, 2, 3 .. 29,30,31) and DD be zero
padded (01,02,03 .. 29, 30, 31)

But other than that, I think it is a good idea to try and lay out a common
language for the cases described.

~~~
chrismorgan
Yeah, DD being short day is just _wrong_ by conventional usage.

------
hden
AWS API versioning: YYYY-MM-DD

[https://docs.aws.amazon.com/sdk-for-
javascript/v2/developer-...](https://docs.aws.amazon.com/sdk-for-
javascript/v2/developer-guide/locking-api-versions.html)

------
macintux
Recent discussion on chronological versioning:
[https://news.ycombinator.com/item?id=21929063](https://news.ycombinator.com/item?id=21929063)

~~~
NetOpWibby
Whoah, that’s my project!

------
CivBase
I could see this being useful in some cases for marketing disambiguation. The
Wifi Alliance should be taking notes. Otherwise, I don't see any reason to use
CalVer over SemVer.

I would rather the version numbers be used to inform users about the nature of
the changes (patches, new features, backwards-incompatible interface changes)
rather than simply when the change was published. I very rarely care about the
publishing date.

------
gregmac
I like that there's a standard page for this for reference, but I disagree
with some of the use cases.

I think it makes sense in a few cases:

* Umbrella-type projects, such as an Operating System, with Ubuntu being a great example.

* Time-dependent projects (where it's more about data), such as tzdata, certificates, tax rates, etc.

* Constantly-changing APIs

I disagree with some of the projects listed, such as Unity and boltons (more
on that below).

\----

I think the trick to this working well is that at least one of the following
must be true:

* You _never_ break backwards compatibility. For example: tzdata, certificates

* There has to be another way to check dependencies. For example: the individual package versions used within Ubuntu

* Release notes (and upgrade notes) need to be _really_ good. For example: include an "upgrade guide" that explicitly calls out breaking changes and how to fix them; summarize the major changes over time; make sure they're digestible by someone who is updating from a few major versions from a couple years ago (without having to read through each incremental guide).

\----

Unity is actually a good counter-example to CalVer as it doesn't follow any of
these rules. A quick search comes up with breaking changes in at least
2019.2.5, 2019.1.0 and 2018.3.0 [1]. To make things worse, they release
frequently -- if I'm updating from say, 2018.2.0, there have been 85 (!)
releases since then. The release notes are very detailed and on individual
pages so it would be a multi-hour effort to read through to even figure out
how complex it'll be to upgrade. This is especially annoying if I'm updating
in a hurry to get an important security fix. At least with SemVer I could
focus on the major releases.

[1] [https://unity3d.com/unity/whats-
new/2019.2.5](https://unity3d.com/unity/whats-new/2019.2.5),
[https://unity3d.com/unity/whats-
new/2019.1.0](https://unity3d.com/unity/whats-new/2019.1.0),
[https://unity3d.com/unity/whats-
new/unity-2018.3.0](https://unity3d.com/unity/whats-new/unity-2018.3.0)

------
awinter-py
APIs and libraries should tell us much more about their semantics so that we
can assert compatibility directly rather than relying on a number

------
barryR
Wireguard uses a hybrid approach: 0.1.20191231

major.minor.YYYYMMDD

~~~
javajosh
Nice. It puts the important stuff first, and even has a nice nested field at
the end (which also puts the important stuff first).

------
albertzeyer
I am just using major.YYYYMMDD.HHMMSS for some of my projects, e.g.
[https://pypi.org/project/better_exchook/](https://pypi.org/project/better_exchook/)
has the latest release 1.20191227.150050. I have never thought about version
numbers for these projects anymore.

------
skrebbel
Any opinions on calver vs semver for, say, open source projects or APIs/SDKs?

~~~
33degrees
For APIs, calver can make a lot of sense, as detailed in Stripe’s blog post on
the subject [https://stripe.com/en-ca/blog/api-
versioning](https://stripe.com/en-ca/blog/api-versioning)

~~~
SahAssar
That's just because they keep compatibility basically forever (they build
middleware to transform older versions to new ones). If you actually want to
remove old versions not so much.

------
joshspankit
The unfortunate truth about calendar versioning is that it pushes devs and
clients toward “freshness” instead of quality.

Same issue that we have in Apple’s design department: change for the sake of
change.

~~~
mhashemi
People like bigger numbers and newer releases regardless of exact versioning
scheme.

SemVer makes that situation worse, by requiring a bigger major release to
break some part of the API. Other failure modes detailed here:
[https://sedimental.org/designing_a_version.html](https://sedimental.org/designing_a_version.html)

~~~
joshspankit
Definitely a fair point. I think we’ve all seen at least one of our favourite
pieces of software fall in to this when the company needed another major
release to bring in funds.

------
flankstaek
Interesting to see that so many of the exemplary projects are python based. I
wonder if there's any correlation there.

~~~
mhashemi
Just a bit of original author bias. If you know other projects, I'd be happy
to merge em!
[https://github.com/mahmoud/calver](https://github.com/mahmoud/calver)

------
SlowRobotAhead
Amazon just adopted this for at least their FreeRTOS releases. 201912.00 is
the latest. Handy enough to know how out of date you are - but overall fairly
useless because I still need to go check and see what’s been released since.
Not to mention some people might flinch if your latest release is 200501.00
even if it’s amazingly complete code.

------
julbaxter
You should probably consider changing the name.
[https://translate.google.com/?hl=fr#fr/en/calvaire](https://translate.google.com/?hl=fr#fr/en/calvaire)

~~~
mrmuagi
Doesn't the prononciation differ -- ver vs. vaire?

~~~
julbaxter
No, same prononciation in French.

