snowspeeder/pi-web
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify CalVer release policy

Browse Source
This commit is contained in:
Federico Jaramillo Martinez
2026-05-17 14:35:58 +02:00
parent 2d8a5d8482
commit c77c47c1d5
5 changed files with 56 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/changeset-changelog/SKILL.md
+8 -4
View File
@@ -49,11 +49,15 @@ Use the package name from `package.json`; for this repo it is `@jmfederico/pi-we
## Choosing patch/minor/major
- `patch`: bug fixes, docs corrections, polish, release-process improvements, small compatible behavior changes.
- `minor`: new user-facing capabilities that are backward compatible.
- `major`: breaking changes to CLI, install expectations, package API, config, data formats, or supported runtime behavior.
This repo uses CalVer shaped as semver: `MAJOR.YYYYMM.PATCH` (for example, `1.202605.3`). The semver `minor` position is the release month, not feature size. Because only the first component represents breaking compatibility, choose Changeset bump types this way:
This repo uses versions like `1.202605.3`. Changesets still uses semver bump types. Routine releases are normally patch-level increments unless the user asks otherwise.
- `patch`: all non-breaking changes, including bug fixes, docs corrections, polish, release-process improvements, small compatible behavior changes, and new backward-compatible user-facing capabilities.
- `minor`: do not use for this repo. The release workflow sets `YYYYMM` from the release date.
- `major`: use only when the user explicitly requests a breaking/major release. Breaking changes can include changes to CLI, install expectations, package API, config, data formats, or supported runtime behavior.
If you believe a change is breaking but the user has not explicitly requested a major release, pause and ask the user to confirm whether to release it as a breaking major version or change the work so it remains non-breaking. Do not infer or perform a major version bump on your own.
During release prep, the npm release skill always computes the version from the release date (`MAJOR.YYYYMM.PATCH`) and increments `PATCH` only when another release already exists for that major/month. Do not ask whether to choose a patch increase or a date change for normal releases.
## Writing good changeset text
.agents/skills/changeset-changelog/evals/evals.json
+7 -1
View File
@@ -10,7 +10,7 @@
{
"id": 2,
"prompt": "Add release notes for this new CLI option before we merge.",
"expected_output": "The assistant should add a changeset fragment for @jmfederico/pi-web with an appropriate minor or patch bump depending on the option, and keep the text user-facing.",
"expected_output": "The assistant should add a changeset fragment for @jmfederico/pi-web using patch for a backward-compatible CLI option, reserve major only for explicit user-requested breaking releases, avoid minor because pi-web uses the semver minor slot for YYYYMM, and keep the text user-facing.",
"files": []
},
{
@@ -18,6 +18,12 @@
"prompt": "Can we update CHANGELOG.md now with the fix I just made?",
"expected_output": "The assistant should explain that normal development should use a .changeset fragment instead of manually editing CHANGELOG.md, then offer to create that fragment.",
"files": []
},
{
"id": 4,
"prompt": "Please write a changeset for this config migration; older config files may not load after it lands.",
"expected_output": "The assistant should identify the possible breaking change and ask the user to confirm whether they explicitly want a breaking major release or want the change made backward-compatible before writing a major changeset.",
"files": []
}
]
}