From 8c1b395c9ad788c7aaf237be3781508b96cfbcd7 Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Wed, 19 Aug 2026 10:12:31 -0700 Subject: [PATCH 1/4] docs(contributing): avoid editor prompt when tagging releases Use 'git tag -a vX.Y.Z -m "vX.Y.Z"' instead of a bare annotated tag, since git tag -a always opens an editor unless -m or -F is given. --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8847192..18c14ee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,9 +18,9 @@ Use an `rc` pre-release tag (e.g. `v1.2.3-rc.1`) before promoting to a stable re 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 `vX.Y.Z` with the version from `package.json`. Pass `-m` so `git tag -a` doesn't open an editor: ```sh - git tag vX.Y.Z + git tag -a vX.Y.Z -m "vX.Y.Z" git push origin vX.Y.Z ``` From 9ce0879a291886271513fe19454470d5fdc7306a Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Mon, 31 Aug 2026 19:45:13 -0700 Subject: [PATCH 2/4] docs(contributing): switch to Calendar Versioning --- CONTRIBUTING.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 18c14ee..b343f57 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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`). Since npm doesn't support the full CalVer format, we approximate it: `YY` is the two-digit year, `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`. Pass `-m` so `git tag -a` doesn't open an editor: +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 -a vX.Y.Z -m "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. From 9a5a0ace888489b9b414f15063d142fdee19be79 Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Mon, 31 Aug 2026 19:57:53 -0700 Subject: [PATCH 3/4] docs(contributing): clarify SemVer compatibility rationale --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b343f57..656a5aa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ ### Versioning -This project follows [Calendar Versioning](https://calver.org/) using a `YY.M.PATCH` scheme (e.g. `v26.8.0`). Since npm doesn't support the full CalVer format, we approximate it: `YY` is the two-digit year, `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`. +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 two-digit year, `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 | | ------------------------------------------- | --------------------- | From d82a1f541622291301eb17a7b2b53cbc64d3d1e8 Mon Sep 17 00:00:00 2001 From: nicomiguelino Date: Mon, 31 Aug 2026 20:01:33 -0700 Subject: [PATCH 4/4] docs(contributing): clarify YY is non-zero-padded --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 656a5aa..ea994c0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ ### Versioning -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 two-digit year, `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`. +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 | | ------------------------------------------- | --------------------- |