mahmoud/calver/calver-adoption

calver-adoption

Take a project from whatever version it has today to its first calendar version, with the scheme documented and the release cut. Five steps, in order. Steps 1 through 4 are always done; step 5 is offered and only executed on request.

Vocabulary: schemes are written in calver.org 26.0 notation. Single letters are unpadded (M, D, W), a leading zero marks zero-padding (0M, 0D, 0W), YYYY is the full year and YY the two-digit year. Never write the doubled MM, DD, or WW: they are deprecated spellings of the unpadded tokens and readers misread them as padded. MINOR and MICRO are ordinary counters. Optional trailing segments go in square brackets: YYYY.M.D[.MICRO].

1. Detect the current version (before asking anything)

Check these sources in order and record every one that yields a value:

1. git tag --sort=-v:refname | head -5
2. package.json → .version
3. pyproject.toml → [project].version, then [tool.poetry].version
4. Cargo.toml → [package].version
5. setup.cfg ([metadata] version) or setup.py (version=)
6. A source file exporting __version__ or VERSION
7. CHANGELOG.md / CHANGES.md / NEWS headings
8. GitHub releases (gh release list --limit 5, if gh is available)

Multiple sources disagreeing: the highest published version (a tag or release) wins, and the drift is reported to the user, since every source gets rewritten in step 5. Also note the tag style (v1.4.2 vs 1.4.2); step 5 must match it.

Nothing found: ask one question, "What's the current version, or has this project not been released yet?" An unreleased project skips every migration concern below; its first release simply uses the chosen scheme's value for the planned release date.

2. Ask about time commitments (one question)

"Do you have support schedules, deprecation windows, LTS cadence, or compliance deadlines that the versioning docs should state?"

Default answer is "none", and most projects say so. If there is something, capture the window lengths for the step 4 paragraph. Two exemplars of what a good answer turns into:

• Ubuntu: each release supported N months; LTS every two years, five

years of support.

• NVIDIA GPU Operator: a new major every six months, twelve months of

support, so end-of-life is readable off the version.

3. Choose a scheme

Present this table and recommend one row based on what step 1 revealed about the project (library vs. application, release cadence, ecosystem).

State the ecosystem constraints that apply, from calver.org's padding section:

• crates.io and Go modules reject zero-padded segments (SemVer's

"MUST NOT contain leading zeroes"). Go modules additionally cannot take a year as the major version without a /v2026-style import path suffix every year, so advise Go libraries against CalVer entirely.

• PyPI normalizes padding away (PEP 440): 2026.04 and 2026.4 are

the same release, and PyPI displays the unpadded form. Pick unpadded.

• npm requires exactly three numeric segments: YYYY.M.MICRO

publishes, bare YYYY.M does not.

• Ordering: the first calendar version must compare greater than the

current version in the ecosystem's comparator. 2026.x > 4.x numerically everywhere, so this almost always holds. If the current major is already large (a project on 3000.x, or already on a date-like number), flag it for manual review before proceeding.

Unpadded is the default; pad only when the versions are sorted as strings (image tags, ISO filenames, object-store keys).

4. Document it

Ask where the versioning statement should live: a README "Versioning" section (default), CONTRIBUTING.md, or a docs page. Insert this paragraph, filled in:

## Versioning

<Project> uses Calendar Versioning. Versions

follow `<SCHEME>`; for example, <EXAMPLE> <one sentence naming

each segment>. <If step 2 yielded commitments: "Each release is

supported for <N> months." / "Deprecations are announced at least <N>

releases before removal.">

Example of the filled sentence for YYYY.M.MICRO: "2026.9.0 is the first release of September 2026; the final number counts fixes within that month."

5. Cut the first release (offer; execute only on request)

1. Compute the first calendar version from the planned release date and

the chosen scheme. Append .0 where the scheme has a MICRO segment.

1. Update every version source found in step 1, in sync. A stale

__version__ next to a new tag is the most common way this goes wrong.

1. Add a changelog entry that names the scheme change and links

https://calver.org.

1. Commit.
2. git tag in the repo's existing style (v prefix or bare, per step

1), then push the tag.

1. Publish with the ecosystem's command: npm publish, uv build then

uv publish (or twine upload), cargo publish, gh release create.

Two cautions to state at the end:

• Verify the registry sorts the new version above the old one before

announcing (npm view <pkg> versions, the PyPI release list, and so on).

• Never retro-tag old commits with calendar numbers. The scheme starts

now; history keeps its old versions.

Install

<!-- GoodTurn: https://goodturn.ai/p/gtp_01m29brgj6eghb36njj0hgtftm -->

• Claude Code: symlink or copy this directory to

~/.claude/skills/calver-adoption.

• Oh My Pi, Codex, and other agents using the Agent Skills layout:

~/.agents/skills/calver-adoption. The skill's name and description are picked up automatically; no other configuration is needed.

Self-update

This skill ships with calver.org and tracks its notation. If the scheme table, the constraints, or the procedure drift from what https://calver.org says, or a step fails on a real project, open an issue or pull request at https://github.com/mahmoud/calver with the fix, bump version to the spec version it now matches, and keep the file under ~200 lines.