# calver.org documents a versioning convention, and now ships a skill to adopt it

> calver is a site and repository that documents Calendar Versioning, the practice of dating releases to the day they ship, along with the variations projects use. It also carries a skill directory that walks a coding agent through adopting the scheme, which is a different kind of contribution than a reference page.

**mahmoud/calver** — 📅 The web's go-to resource for Calendar Versioning info.

- Repository: https://github.com/mahmoud/calver
- Website: https://calver.org
- Stars: 586 · Forks: 35
- Language: CSS
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/mahmoud-calver

## A convention, described rather than implemented

calver is a project versioning convention based on the calendar dates of project releases, instead of arbitrary numbers, and the repository describes itself as the go-to resource for Calendar Versioning information. The homepage is calver.org, and the primary language of the repository is listed as CSS, which is a clue that this is a documentation site rather than a library.

The argument for the convention is made by reference rather than by assertion. The README points at a page on designing a version for the benefits, and at an overview page for the multiple variations, to custom fit all projects. Then it lists the range of projects already using the idea, from Ubuntu to Twisted to PyCharm to C itself and more.

That list is the argument. If the standard library language C and three of the better known Linux and JVM tools number their releases by date, then dating releases is a normal engineering practice rather than an eccentricity, and the interesting question becomes which of the several variations to pick.

The topic also has a well known lineage in the design literature, and the README links out to the source material on designing a version rather than re-deriving it here. So the repository is a curated entry point, and the depth lives in the linked pages rather than in the README itself.

## The site is generated, and you can preview a change before you open a pull request

The Contributing section explains the mechanics of the site, and it is short because the tooling does the work.

calver.org is generated with Chert and Python, so a contributor who wants to submit a pull request directly can install Chert with pip and run chert serve from within the repository directory, which gives a live-updating preview of what the change will look like.

That is a good contributor experience for a documentation project, and it is the kind of thing that tells you the site is meant to be edited by people who did not write the original. The two commands are pip install chert and chert serve, and the second one has to be run from inside the repository, which means the project expects a local checkout rather than a hosted editing workflow.

The repository layout backs this up. There is a chert.yaml configuration file, a custom.py file, an entries/ directory that presumably holds the content pages, themes/ for the presentation, uploads/ for images, a TODO.md with the remaining work, a .workstream-plans/ directory, and a skills/ directory.

The images in the README, including a diagram of a version tree, live in uploads/, so the media is versioned with the content rather than fetched from a CDN, which is a reasonable choice for a site that should be readable as a plain repository.

## The skills directory is the part that changed the shape of the project

The most interesting addition in the README is a paragraph about adopting CalVer with a coding agent. It says to point the agent at skills/calver-adoption/SKILL.md, a skill that detects the current version, picks a scheme, writes the docs paragraph, and cuts the first release.

Read that list of four actions closely, because it describes a workflow rather than a document. Detect the current version, which is the part that is genuinely hard, because a repository can be on a conventional numeric scheme, on semantic versioning, or on a date scheme with a different format, and the agent has to work out which. Pick a scheme, which is a decision the tool should not make silently. Write the docs paragraph, which is the visible output most projects need and most forget. And cut the first release, which is the point of the whole exercise, because a versioning convention only counts once there is a version that uses it.

This is a different kind of contribution from the rest of the repository. A reference site tells you what CalVer is; a skill tells a tool how to apply it to your project. Packaging the second as a SKILL.md file in a skills/ directory means it can be handed to an agent that will act on it.

The pairing is also a good sign about how the project thinks about adoption. A convention nobody applies changes nothing, and the most common reason a convention is not applied is that nobody remembers to apply it or cannot decide which variation fits. A skill that detects the current state and picks a scheme removes exactly those two obstacles.

## The variations are the real decision, and the site says so

The README says the overview page documents multiple variations to custom fit all projects, and that the users page lists the projects that use it. The link structure confirms the split. The overview has an anchor for Ubuntu, the users page has one for other notable projects and for languages and standards, and the overview is where the variations live.

That structure matters because there is no single CalVer format. A project that ships on a schedule needs the date. A project that ships on demand and wants to show age needs the date plus a sequence, because two releases on the same day would otherwise collide. A project that wants to mark a breaking change needs a way to say so. Each of those is a variation, and the choice between them depends on the release cadence and the compatibility policy of the project rather than on taste.

The practical value of a central reference here is that the variations get written down once. Without it, every project that dates its releases reinvents the suffix convention, and then two projects that both say 2026.10.1 mean different things.

The README does not reproduce the variations, so anyone reading only the repository file will not learn them. That is a limit of the README, not of the project, but it means the site itself is the deliverable and the repository is the source for it.

## What a documentation project is not

It is worth being blunt about the category, because the repository type is not obvious from the topic.

calver does not version anything for you. There is no tool, no library and no command line here. It does not check your version numbers, it does not rewrite your changelog, and it does not tag a release. The skills/calver-adoption skill is a set of instructions for an agent, not an executable that performs the work on its own, and the project as a whole is the documentation that a skill and a team would both draw on.

There is also no package to install and no dependency to add. The install step, if you can call it that, is pip install chert followed by chert serve, and that is for contributing to the site, not for using Calendar Versioning in your own project. Using the convention itself requires nothing but reading and deciding.

The second limit is the audience. The README is written for maintainers and contributors to the convention, and the pages it links to are reference material. If you are looking for a tool that stamps versions onto your packages, this is the wrong repository and no part of it will help.

The third limit is the licence, which needs a decision. The repository records a custom licence that GitHub cannot classify, with the terms in the LICENSE file. For a documentation project that many people link to, that is worth reading before you quote it, mirror it, or build your own guidance on top of it. It is a description of what to check, not advice on what the terms mean.

## Maintenance, and where the site itself stands

The repository is not archived and the last push was on 2026-10-10, so the site is being worked on. There are no GitHub releases, which is consistent with what the project is: a site with a stable URL rather than a package with a version history. The version scheme of the site itself is a separate question, and the README does not discuss it.

The TODO.md file in the repository root is a good signal about where the work is. A project that maintains a public TODO file is telling you its priorities in public, and it is also telling you that the content is not finished. The .workstream-plans/ directory suggests the same thing from another angle, since it implies the work is planned in streams rather than filed as loose issues.

For an evaluator, the two things to weigh are these. First, the convention itself is not new, and the value of the site is in its curation and its links, not in novelty. Second, the skill for coding agents is the novel part, and it is the part most likely to change, because the format and the expectations around agent skills are still moving.

So the sensible order is to read the overview and the users pages first and take the convention from there, and to look at the skill only if you actually intend to hand it to an agent.

## Conclusion

Adopt calver if you are deciding how to number your releases and want the scheme options laid out with the reasoning, or if you want a coding agent to apply one consistently. Do not adopt it as a versioning tool, because it is documentation and a prompt file, not something that stamps your releases. Before you follow its advice, read the overview and the users pages for the variations, and check the licence in the LICENSE file, since the repository records a custom licence that GitHub cannot classify.

## FAQ

### What is calver?

calver is a project versioning convention based on the calendar dates of project releases instead of arbitrary numbers, and the repository and the site calver.org document it, including the benefits, the multiple variations and the projects that use it, from Ubuntu to Twisted to PyCharm to C itself.

### How do I contribute to calver.org?

The site is generated with Chert and Python. Install it with pip install chert, then run chert serve from within the repository directory for a live-updating preview of your change before opening a pull request. Questions and issues can be opened on the repository.

### What does the calver skill for coding agents do?

The README says to point an agent at skills/calver-adoption/SKILL.md, a skill that detects the current version, picks a scheme, writes the docs paragraph, and cuts the first release.

### Does calver version my project for me?

No. The repository contains no tool, library or command that stamps versions. It is a documentation site and a set of instructions, so adopting Calendar Versioning means reading the variations, choosing one, and applying it yourself, optionally with the help of a coding agent given the adoption skill.

## Sources

- [Issues](https://github.com/mahmoud/calver/issues)
- [mahmoud/calver on GitHub](https://github.com/mahmoud/calver)
- [Project website](https://calver.org)
- [README](https://github.com/mahmoud/calver/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mahmoud-calver