Archived
docs: clarify CalVer release policy
This commit is contained in:
Federico Jaramillo Martinez
@@ -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
|
||||
|
||||
|
||||
@@ -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": []
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -59,34 +59,43 @@ If there is no GitHub Actions publish workflow, stop and explain that one must b
|
||||
- If there are unrelated or user-owned uncommitted changes, pause and ask before including, stashing, or working around them.
|
||||
- Pull/rebase only when it is safe and the user has not left local work that could be disrupted.
|
||||
|
||||
2. **Review pending changesets**
|
||||
2. **Review and normalize pending changesets**
|
||||
- Run:
|
||||
```bash
|
||||
npm run changelog:status
|
||||
```
|
||||
- Inspect `.changeset/*.md` files.
|
||||
- If there are no changesets but there are user-visible changes to release, pause and ask whether to add a changeset. Do not create a low-quality release note just to proceed.
|
||||
- If changesets exist, make sure their text is user-facing and their bump types are plausible.
|
||||
- If changesets exist, make sure their text is user-facing.
|
||||
- For `pi-web`, non-breaking changesets must use `patch` even for new features. The package uses CalVer shaped as semver: `MAJOR.YYYYMM.PATCH`. The semver `minor` position is the release month, not feature size.
|
||||
- If a pending changeset uses `minor` for a non-breaking change, edit its frontmatter to `patch` before versioning. Do not ask the user whether to use a patch increase or date change.
|
||||
- Use `major` only when the user explicitly requests a breaking/major release.
|
||||
- If you believe the pending changes introduce a breaking change but the user has not explicitly requested a major release, pause before versioning and ask the user to confirm whether this should be released as a breaking major version or changed to remain non-breaking.
|
||||
|
||||
3. **Choose or confirm the new version**
|
||||
- If the user gave an exact version, use it.
|
||||
- If they asked for `patch`, `minor`, `major`, or similar, compute/confirm the next compatible version.
|
||||
- If the repository uses a custom scheme, preserve it. For example, `pi-web` uses versions like `1.202605.3`; a routine next release in the same month should increment the final component unless the user says otherwise.
|
||||
- Changesets uses semver bump types. For routine `pi-web` releases, patch changesets normally produce the desired final-component increment.
|
||||
- If uncertain, ask for confirmation before changing files.
|
||||
3. **Compute the `pi-web` CalVer version**
|
||||
- For `pi-web`, always compute the version from the release date as `MAJOR.YYYYMM.PATCH`.
|
||||
- Use the current date at release time for `YYYYMM` (for example, `date +%Y%m`). Do not ask whether to use a same-month patch increase or a date change.
|
||||
- Keep the current `MAJOR` unless the user explicitly requests a breaking/major release. Do not infer or perform a major version bump on your own.
|
||||
- Set `PATCH` deterministically:
|
||||
- If the current package version already has the target `MAJOR` and release-month `YYYYMM`, use current patch + 1.
|
||||
- Otherwise use patch `0` for the first release of that major/month.
|
||||
- If npm already has the computed version, increment only `PATCH` until an unpublished version is found.
|
||||
- If the user says `patch`, `minor`, `new version`, `new release`, `publish`, or similar without an exact version, still use this CalVer algorithm. Treat `minor` as a non-breaking release request, not as permission to let Changesets increment semver minor arbitrarily.
|
||||
- If the user gives an exact version, use it only when they clearly intend that exact value. Otherwise preserve the CalVer rule above.
|
||||
- If the computed CalVer target would be lower than or equal to the current package version because of clock/version inconsistency, stop and explain the inconsistency instead of inventing a non-CalVer version.
|
||||
|
||||
4. **Generate changelog and version files**
|
||||
- Prefer the Changesets version step:
|
||||
- Run the Changesets version step after normalizing non-breaking changesets to `patch`:
|
||||
```bash
|
||||
npm run release:version
|
||||
```
|
||||
- This consumes pending `.changeset/*.md` fragments, updates `CHANGELOG.md`, updates `package.json`, and updates the npm lockfile when applicable.
|
||||
- Review the generated `CHANGELOG.md` section. It should be suitable for GitHub Release notes.
|
||||
- If the user requested an exact version and Changesets produced a different version, adjust carefully:
|
||||
- Changesets may produce a semver bump that does not match the computed CalVer target, especially on the first release of a new month. That is expected; enforce the computed target with:
|
||||
```bash
|
||||
npm version <new-version> --no-git-tag-version
|
||||
npm version <computed-calver-version> --no-git-tag-version
|
||||
```
|
||||
Then update the generated `CHANGELOG.md` heading to match the exact version. This manual changelog edit is acceptable during release prep; normal development should use changeset fragments instead.
|
||||
- Update the newly generated `CHANGELOG.md` heading to match the computed CalVer version if Changesets used a different heading. This manual changelog heading edit is acceptable during release prep; normal development should still use changeset fragments instead.
|
||||
- Review the generated `CHANGELOG.md` section. It should be suitable for GitHub Release notes.
|
||||
- Do not use plain `npm version <new-version>` because it creates a local git tag as a side effect; releases should be controlled via GitHub.
|
||||
|
||||
5. **Run checks before creating the release**
|
||||
|
||||
@@ -4,13 +4,13 @@
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Please make a new npm release for this package. Use the next patch version.",
|
||||
"expected_output": "The assistant should inspect package.json, pending Changesets, and the GitHub Actions publish workflow; run changeset version to generate CHANGELOG.md/version files; avoid local npm publish; run verification; commit/push; create a GitHub Release using changelog notes; monitor the publish workflow; and verify npm.",
|
||||
"expected_output": "The assistant should inspect package.json, pending Changesets, and the GitHub Actions publish workflow; normalize non-breaking Changesets to patch; compute the pi-web CalVer target as MAJOR.YYYYMM.PATCH using the release date and next patch for that major/month; run changeset version; enforce the computed version if needed; avoid local npm publish; run verification; commit/push; create a GitHub Release using changelog notes; monitor the publish workflow; and verify npm.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "bump npm to 1.202605.4 and publish it",
|
||||
"expected_output": "The assistant should use the explicit version, avoid local npm publish, generate/update CHANGELOG.md through Changesets, enforce the requested version with --no-git-tag-version only if needed, push a release commit, create a GitHub Release that triggers publish.yml, and report action/npm status.",
|
||||
"expected_output": "The assistant should use the clearly requested exact version, avoid local npm publish, generate/update CHANGELOG.md through Changesets, enforce the requested version with --no-git-tag-version only if needed, push a release commit, create a GitHub Release that triggers publish.yml, and report action/npm status.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
@@ -18,6 +18,18 @@
|
||||
"prompt": "The npm publish action failed last night; can you get the release published?",
|
||||
"expected_output": "The assistant should inspect the failed GitHub Actions run and rerun or fix it through GitHub Actions. It should not use local npm publish as a workaround, and should preserve the generated changelog/release notes.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "make a new release; I added a non-breaking feature changeset that says minor",
|
||||
"expected_output": "The assistant should not ask whether to use a patch bump or date change. It should treat non-breaking pi-web changesets as patch, compute MAJOR.YYYYMM.PATCH from the release date, run release prep, and enforce the computed CalVer version before creating the GitHub Release.",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "make a new release; the API auth config format changed and old config files probably won't work anymore",
|
||||
"expected_output": "The assistant should recognize a possible breaking change and pause to ask the user whether to proceed as an explicitly requested breaking major release or change the work to remain non-breaking. It should not infer or perform a major version bump without user confirmation.",
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
---
|
||||
"@jmfederico/pi-web": patch
|
||||
---
|
||||
|
||||
Document the Pi Web CalVer release rule so releases use the release month, increment the patch component for additional releases in the same month, and require explicit user confirmation before any breaking major release.
|
||||
Reference in New Issue
Block a user