Skip to content

docs(contributing): switch to Calendar Versioning #76

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nicomiguelino merged 4 commits into from
Sep 1, 2026
Merged

docs(contributing): switch to Calendar Versioning #76

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8c1b395
docs(contributing): avoid editor prompt when tagging releases
nicomiguelino Aug 19, 2026
9ce0879
docs(contributing): switch to Calendar Versioning
nicomiguelino Sep 1, 2026
9a5a0ac
docs(contributing): clarify SemVer compatibility rationale
nicomiguelino Sep 1, 2026
d82a1f5
docs(contributing): clarify YY is non-zero-padded
nicomiguelino Sep 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,27 @@

### Versioning

This project follows [Semantic Versioning](https://semver.org/). Git tags are always `v`-prefixed (e.g. `v1.2.3`). Pre-release tags use the format `v1.2.3-rc.1`.
This project follows [Calendar Versioning](https://calver.org/) using a `YY.M.PATCH` scheme (e.g. `v26.8.0`), a SemVer-compatible variant of CalVer. npm requires `package.json` versions to be valid [SemVer](https://semver.org/), which disallows leading zeros in numeric identifiers, so `YY` is the last two digits of the year as a non-zero-padded number (e.g. `26` for 2026), `M` is the non-zero-padded month, and `PATCH` resets to `0` for the first release of a given year/month and increments for subsequent releases within that same month. Git tags are always `v`-prefixed (e.g. `v26.8.0`). Pre-release tags use the format `v26.8.0-rc.1`.

| Change type | Example |
| --------------------------------- | --------------------- |
| Bug fix (patch) | `v0.0.17` → `v0.0.18` |
| New feature, non-breaking (minor) | `v0.0.17` → `v0.1.0` |
| Breaking change (major) | `v0.1.0` → `v1.0.0` |
| Change type | Example |
| ------------------------------------------- | --------------------- |
| Another release in the same month | `v26.8.0` → `v26.8.1` |
| First release in a new month (same year) | `v26.8.1` → `v26.9.0` |
| First release in a new year | `v26.9.0` → `v27.1.0` |

Use an `rc` pre-release tag (e.g. `v1.2.3-rc.1`) before promoting to a stable release.
Use an `rc` pre-release tag (e.g. `v26.8.0-rc.1`) before promoting to a stable release.

### Steps

1. Bump the version in `package.json`.
2. Commit the version bump and open a PR against `main`.
3. Once merged, tag the release, replacing `vX.Y.Z` with the version from `package.json`:
3. Once merged, tag the release, replacing `vYY.M.PATCH` with the version from `package.json`. Pass `-m` so `git tag -a` doesn't open an editor:
```sh
git tag vX.Y.Z
git push origin vX.Y.Z
git tag -a vYY.M.PATCH -m "vYY.M.PATCH"
git push origin vYY.M.PATCH
```

Pushing the tag triggers the release workflow automatically:

- **Stable releases** (e.g. `v1.2.3`): publishes to npm and creates a GitHub release.
- **Release candidates** (e.g. `v1.2.3-rc.1`): publishes to npm under the `rc` dist-tag only.
- **Stable releases** (e.g. `v26.8.0`): publishes to npm and creates a GitHub release.
- **Release candidates** (e.g. `v26.8.0-rc.1`): publishes to npm under the `rc` dist-tag only.