Why I chose Calendar Versioning for Vigilant

Vigilant is an application designed to monitor all aspects of your website. While many features are still in development, the current version (2025.4) is stable and usable. Given its ongoing development, I’ve chosen Calendar Versioning (CalVer) to version Vigilant. Here’s why.

Calendar versioning has a few benefits, here is the short list, I'll explain each benefit in greater detail below:

• No arbitrary major versions for breaking changes

• Eliminates pressure for ‘big’ releases

• Instant context of time

• Encourages regular, iterative updates

No arbitrary major versions for breaking changes

SemVer is the better choice for libraries because it gives developers a clear signal about compatibility. If you're depending on a library and it jumps from 2.3.4 to 3.0.0, you know there are breaking changes and you need to pay attention before upgrading. Libraries need that kind of precision since they’re used as building blocks in many other projects.

But for actual projects like Vigilant, SemVer can get awkward fast. Every time you make a breaking change, you're supposed to bump the major version. That’s fine in theory, but in practice it leads to version numbers climbing quickly and doesn’t actually tell you much about when that version was released or how old your current version is.

CalVer works better for projects because it sets the expectation that things change over time. You don't have to save up changes for a “big” release or worry about version number inflation. Users get a version that immediately shows when it was released, and they can decide if they’re due for an update just by looking at the date.

The goal of Vigilant is also to be up-to-date. When you update you should review the breaking changes for each release and update accordingly.

Eliminates pressure for ‘big’ releases

With SemVer, there’s often this pressure to group a bunch of changes together to justify a new major version. That leads to features to be delayed until it's worth releasing multiple big changes.

With CalVer, every release is just another point in time. There's no buildup to a big moment and breaking changes can be introduced gradually, in smaller, easier-to-manage chunks. This sets the expectation that each release might include a breaking change, and that’s okay.

Calendar Versioning avoids the need for large, sudden releases by incorporating breaking changes into regular updates. This gives people who host Vigilant the expectation that every release may contain a breaking change.

Instant context of time

With traditional versioning like SemVer, a version number like 1.22 doesn’t tell you anything about when that version was released. Is it recent? Is it two years old? Are you running something outdated? You’d have to dig through a changelog or commit history just to find out.

Calendar Versioning solves that instantly. A version like 2025.4 makes it obvious that it was released in April 2025. If you're running 2024.12, then you already know you're a few months behind, no extra research needed. It adds helpful context just by glancing at the version number.

This is especially useful when debugging issues or comparing versions. It’s easier to tell whether a fix or feature exists in your current version, and you can quickly spot if someone else is running something newer. That kind of visibility makes maintaining and updating Vigilant simpler, both for me as the developer and for anyone hosting it.

Encourages regular, iterative updates

Open source projects depend on a whole stack of other open source tools and libraries, and those dependencies are constantly evolving. Security patches, performance improvements, new features, they all come in through regular updates. It’s best practice to stay current whenever possible, even if your own code hasn’t changed.

Calendar Versioning encourages that kind of steady, iterative release cycle. With a date-based versioning scheme, it's normal to push out new releases just to update dependencies or fix minor things. There's no pressure to bundle a bunch of features or changes into one "worthy" release, you just ship regularly and keep moving forward.

Vigilant, for example, is built with Laravel, which releases updates every week. Even if I don’t touch Vigilant’s own logic, there’s still value in releasing a new version just to stay on top of Laravel’s updates. CalVer makes that cadence feel natural.

It also builds trust. People using Vigilant know the project is alive, current, and being maintained, and they can see that just by looking at the version history.

Conclusion

Calendar Versioning fits the way Vigilant is built and maintained, regularly updated, and always evolving. It removes the friction of traditional versioning, gives clear context at a glance, and supports the kind of steady, dependable release cycle I want for this project. For libraries, SemVer still makes sense. But for an application like Vigilant, CalVer just works better.