chore: add changeset release workflow

2026-05-13 12:58:40 +02:00
parent 2951742c7b
commit cf43c95385
9 changed files with 1434 additions and 1 deletions
@@ -0,0 +1,174 @@
+---
+name: npm-release-via-github-actions
+description: Use this skill whenever the user asks for a new npm version, npm release, package release, new release, version bump, publishing to npm, cutting a GitHub release, tagging a release, or anything similar. It publishes through GitHub Actions and GitHub Releases, not from the local machine, and uses Changesets to generate CHANGELOG.md/release notes. Trigger even for casual phrasing like "ship a release", "bump npm", "publish the package", or "make a new version".
+---
+
+# Publish npm packages via GitHub Actions
+
+The user explicitly does **not** want local npm publishing. For release requests, route publishing through the repository's GitHub Actions workflow, usually triggered by a published GitHub Release.
+
+This project also uses Changesets for changelog generation. Release prep should consume `.changeset/*.md` fragments into `CHANGELOG.md` before the GitHub Release is created.
+
+## Core rules
+
+Do not publish from the local machine.
+
+Avoid these commands unless the user explicitly overrides this skill for an unusual emergency:
+
+- `npm publish`
+- `npm run publish:npm`
+- `pnpm publish`, `yarn publish`, or equivalent package-manager publish commands
+- any local publish workaround after a GitHub Actions problem
+
+It is OK to run local safety checks and release-prep commands that do not publish, such as:
+
+- `npm run verify`
+- `npm run build`
+- `npm run pack:dry`
+- `npm run changelog:status`
+- `npm run release:version`
+- `npm version <version> --no-git-tag-version` when an exact custom version needs to be enforced
+
+## First inspect the repository release setup
+
+Before acting, read:
+
+1. `package.json` for package name, current version, scripts, and package manager.
+2. `package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock` if present, so version bumps keep lockfiles consistent.
+3. `.changeset/config.json` and pending `.changeset/*.md` files, if present.
+4. `.github/workflows/publish.yml` or similarly named release workflow.
+
+Confirm the workflow publishes on GitHub, preferably from one of these triggers:
+
+```yaml
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+```
+
+For the `pi-web` repository, the expected workflow is `.github/workflows/publish.yml`; it publishes with `npm publish --access public --provenance` from GitHub Actions. Use the GitHub Release path by default.
+
+If there is no GitHub Actions publish workflow, stop and explain that one must be added or fixed. Do not fall back to local `npm publish`.
+
+## Standard release workflow
+
+1. **Check repo state**
+   - Run `git status --short --branch`.
+   - Ensure you are on the intended branch, usually `main`.
+   - 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**
+   - 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.
+
+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.
+
+4. **Generate changelog and version files**
+   - Prefer the Changesets version step:
+     ```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:
+     ```bash
+     npm version <new-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.
+   - 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**
+   - Run the repository's normal verification commands, for example:
+     ```bash
+     npm run verify
+     npm run build
+     npm run pack:dry
+     ```
+   - If checks fail, fix the issue or report it. Do not create the GitHub Release until the release commit is sound.
+
+6. **Commit and push the release prep**
+   - Commit only intended release changes. Typical files include:
+     - `package.json`
+     - `package-lock.json`
+     - `CHANGELOG.md`
+     - consumed/deleted `.changeset/*.md` fragments
+   - Use:
+     ```bash
+     git add package.json package-lock.json CHANGELOG.md .changeset
+     git commit -m "chore(release): v<new-version>"
+     git push origin main
+     ```
+   - If there are other intentional changes required for the release, include them deliberately and mention them.
+
+7. **Create a GitHub Release to trigger publishing**
+   - Prefer release notes from the generated changelog instead of generic generated notes.
+   - Extract the new version's section from `CHANGELOG.md` into a temporary notes file if useful.
+   - Use the pushed commit on `main` as the target:
+     ```bash
+     gh release create v<new-version> \
+       --target main \
+       --title "v<new-version>" \
+       --notes-file /tmp/pi-web-release-notes-v<new-version>.md
+     ```
+   - If a clean notes file is not practical, `--generate-notes` is acceptable, but prefer the Changesets-generated text because it is curated.
+   - Creating a non-draft published release triggers `on: release: types: [published]`.
+   - If the user specifically wants to review notes first, create a draft release, then publish it through GitHub when approved. Remember: draft creation will not trigger publishing until it is published.
+
+8. **Monitor GitHub Actions**
+   - Find the publish run:
+     ```bash
+     gh run list --workflow publish.yml --limit 5
+     ```
+   - Watch it:
+     ```bash
+     gh run watch <run-id>
+     ```
+   - If it fails, inspect logs:
+     ```bash
+     gh run view <run-id> --log-failed
+     ```
+   - Fix by committing and creating a new release/tag if needed, or rerun the failed GitHub Actions job when the failure is transient. Do not publish locally as a workaround.
+
+9. **Verify npm registry publication**
+   - After the workflow succeeds, verify:
+     ```bash
+     npm view <package-name> version
+     npm view <package-name>@<new-version> dist.tarball
+     ```
+   - If npm has not updated yet, wait briefly and check again.
+
+## Reruns and special cases
+
+- If a GitHub Actions publish run failed due to a transient infrastructure issue, prefer `gh run rerun <run-id> --failed` or rerun the workflow in GitHub.
+- If using `workflow_dispatch`, pass the intended ref/tag explicitly where possible:
+  ```bash
+  gh workflow run publish.yml --ref v<version>
+  ```
+  Use this mainly for reruns or repositories designed around manual dispatch. For normal releases, prefer a published GitHub Release.
+- If the npm version already exists, npm will reject publishing. Bump to a new version and create a new release; do not try to overwrite an existing npm version.
+- If a GitHub Release/tag was created incorrectly, fix it on GitHub with care and tell the user exactly what changed.
+- Never use local `npm publish` as a workaround for a GitHub Actions or npm provenance issue.
+
+## Final response format
+
+After completing or attempting a release, summarize concisely:
+
+- Version requested/released
+- Changelog source: generated `CHANGELOG.md` section or other notes used
+- Commit hash and pushed branch
+- GitHub Release URL
+- GitHub Actions run URL and status
+- npm verification result, if published
+- Any follow-up needed from the user