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

chore: add changeset release workflow

Browse Source
This commit is contained in:
Federico Jaramillo Martinez
2026-05-13 12:58:40 +02:00
parent 2951742c7b
commit cf43c95385
9 changed files with 1434 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/changeset-changelog/SKILL.md
+109
View File
@@ -0,0 +1,109 @@
---
name: changeset-changelog
description: Use this skill whenever the user asks about changelogs, Changesets, release notes, conventional commits, commit messages for release notes, or making user-visible project changes that should appear in a future npm/GitHub release. Trigger when preparing commits or PRs that include features, fixes, docs users rely on, package behavior changes, CLI changes, install changes, or release process changes. This skill keeps CHANGELOG.md generated at release time instead of manually edited during development.
---
# Changeset changelog workflow
This project uses Changesets so release notes are collected as small per-change markdown files during development and converted into `CHANGELOG.md` during release prep. This avoids multiple branches editing the same `CHANGELOG.md` section.
## Core rules
- For user-visible changes, add a `.changeset/*.md` fragment.
- Do not manually edit `CHANGELOG.md` during normal feature/fix work. Let `changeset version` generate or update it during release prep.
- Use Conventional Commit style for commit messages when committing, but do not rely on commit messages as the only changelog source.
- Write release notes for users, not as raw implementation logs.
## When a changeset is needed
Create a changeset for changes that affect users, operators, package consumers, or release/install behavior, including:
- New features or UI behavior
- Bug fixes users can observe
- CLI, package exports, install, service, or configuration changes
- Documentation users rely on for setup or usage
- Dependency/runtime requirement changes
- Release-process changes that future maintainers need to see
A changeset is usually not needed for purely internal refactors, tests, lint-only changes, build cleanup, or agent-only project skills unless the user wants them recorded. When in doubt, ask briefly or create a patch changeset with a clear note.
## How to create a changeset
Prefer the CLI when interaction is practical:
```bash
npm run changeset
```
For non-interactive agent work, create a file manually under `.changeset/` with a unique kebab-case name:
```md
---
"@jmfederico/pi-web": patch
---
Fix session command handling so browser/API restarts do not interrupt active Pi sessions.
```
Use the package name from `package.json`; for this repo it is `@jmfederico/pi-web`.
## 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 versions like `1.202605.3`. Changesets still uses semver bump types. Routine releases are normally patch-level increments unless the user asks otherwise.
## Writing good changeset text
Keep entries concise and user-facing:
- Start with an imperative or past-tense summary of the user impact.
- Mention the affected area when useful: sessions, web UI, CLI, install, extensions, release workflow.
- Avoid internal-only details like file names unless they help users.
- Avoid vague notes like “misc fixes” or “update code”.
Good examples:
```md
Preserve active Pi sessions when the web/API development service restarts.
```
```md
Add a project-local release workflow skill that publishes npm packages through GitHub Actions instead of local publishing.
```
Poor examples:
```md
Changed sessionCommandService.ts.
```
```md
Fix stuff.
```
## Conventional Commit guidance
When asked to commit, use Conventional Commit style:
- `feat: add persistent session reconnect handling`
- `fix: preserve queued commands across API restarts`
- `docs: document systemd user services`
- `chore(release): v1.202605.4`
Keep commits and changesets aligned, but remember their audiences differ:
- Commit message: developer history.
- Changeset text: future release notes for users.
## Release prep handoff
During release prep, use the `npm-release-via-github-actions` skill. It should run:
```bash
npm run release:version
```
That consumes `.changeset/*.md`, updates `package.json` / lockfile versions, and generates or updates `CHANGELOG.md`. Publishing still happens only through GitHub Actions after a GitHub Release is published.
.agents/skills/changeset-changelog/evals/evals.json
+23
View File
@@ -0,0 +1,23 @@
{
"skill_name": "changeset-changelog",
"evals": [
{
"id": 1,
"prompt": "We fixed the session reconnect bug. Please prepare the changelog entry and commit message.",
"expected_output": "The assistant should create or propose a .changeset/*.md patch fragment with user-facing wording and a Conventional Commit style fix message, without editing CHANGELOG.md directly.",
"files": []
},
{
"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.",
"files": []
},
{
"id": 3,
"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": []
}
]
}
.agents/skills/npm-release-via-github-actions/SKILL.md
+174
View File
@@ -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
.agents/skills/npm-release-via-github-actions/evals/evals.json
+23
View File
@@ -0,0 +1,23 @@
{
"skill_name": "npm-release-via-github-actions",
"evals": [
{
"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.",
"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.",
"files": []
},
{
"id": 3,
"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": []
}
]
}
.changeset/README.md
+8
View File
@@ -0,0 +1,8 @@
# Changesets
Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
with multi-package repos, or single-package repos to help you version and publish your code. You can
find the full documentation for it [in our repository](https://github.com/changesets/changesets).
We have a quick list of common questions to get you started engaging with this project in
[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).
.changeset/config.json
+11
View File
@@ -0,0 +1,11 @@
{
"$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
"changelog": "@changesets/cli/changelog",
"commit": false,
"fixed": [],
"linked": [],
"access": "public",
"baseBranch": "main",
"updateInternalDependencies": "patch",
"ignore": []
}
.changeset/lucky-badgers-release.md
+5
View File
@@ -0,0 +1,5 @@
---
"@jmfederico/pi-web": patch
---
Formalize release notes with Changesets and project-local skills for changelog and npm publishing workflows.
package-lock.json
Generated
+1076
View File
File diff suppressed because it is too large Load Diff
package.json
+5 -1
View File
@@ -37,7 +37,10 @@
"pack:dry": "npm pack --dry-run",
"prepublishOnly": "npm run verify",
"publish:npm": "npm publish --access public",
"prepare": "node scripts/install-git-hooks.mjs"
"prepare": "node scripts/install-git-hooks.mjs",
"changeset": "changeset",
"release:version": "changeset version",
"changelog:status": "changeset status"
},
"dependencies": {
"@codemirror/lang-css": "^6.3.1",
@@ -61,6 +64,7 @@
"ws": "^8.18.3"
},
"devDependencies": {
"@changesets/cli": "^2.31.0",
"@earendil-works/pi-coding-agent": "^0.74.0",
"@eslint/js": "^10.0.1",
"@types/node": "^24.10.1",