docs: consolidate changeset guidance into .changeset/README - #291
Conversation
Replace the misleading empty-changeset-for-all-chores rule with a decision table aligned to check-changeset-required.mjs. Agents should skip .changeset files on non-publishable PRs and add real changesets only for user-visible npm package changes under publishable paths. Co-authored-by: Silvan <adlerhurst@users.noreply.github.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
Pull request overview
Clarifies the repository’s Changesets policy so agents only add .changeset/*.md files when a PR actually touches publishable npm package paths, reducing unnecessary empty changesets on Go-only/internal/docs-only work.
Changes:
- Updates the changeset gate script messaging to reflect “publishable path” rules and the (rare) empty-changeset case.
- Adds a Changesets subsection to
AGENTS.mdwith the publishable path list (matching the script), a decision table, and a local verification command. - Aligns the PR template and GitHub Copilot/TypeScript review instructions to reference the new decision table.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/check-changeset-required.mjs | Clarifies gating comments/errors to be path-based and documents the rare empty-changeset scenario. |
| AGENTS.md | Documents publishable paths + decision table for when to add no/real/empty changeset. |
| .github/PULL_REQUEST_TEMPLATE.md | Prompts authors to state one of the decision-table outcomes in PR descriptions. |
| .github/instructions/typescript.instructions.md | Points TypeScript reviewers/agents to the decision table for changeset decisions. |
| .github/copilot-instructions.md | Aligns Copilot guidance with the decision-table-based changeset rules. |
|
Thanks, this is a useful correction to the previous guidance. I think the direction is right: agents should stop creating empty changesets for docs/CI/internal-only PRs. A couple of things I would adjust before merging:
Related small structure note: after adding |
|
@mridang must be a member of the zitadel team on Vercel to deploy. Learn more about collaboration on Vercel and other options here. |
Move the full PR workflow (decision table, publishable paths, CI gate, how-to, anti-patterns, verify command) from root AGENTS.md into .changeset/README.md. Replace the long AGENTS.md Changesets section with a short link to the README anchors. Update PR template, copilot instructions, release-docs instructions, and check-changeset-required error messages to point at the README. Co-authored-by: Silvan <adlerhurst@users.noreply.github.com>
Co-authored-by: Silvan <adlerhurst@users.noreply.github.com>
cursor
Bot
changed the title
|
@adlerhurst must be a member of the zitadel team on Vercel to deploy. Learn more about collaboration on Vercel and other options here. |
Summary
Consolidates changeset PR workflow into
.changeset/README.mdas the single source of truth. RootAGENTS.mdnow links to README anchors (#publishable-npm-packages,#decision-table) instead of duplicating ~70 lines.The README now includes the full agent/PR workflow: CI gate, publishable paths, user-visible definition, decision table, how-to (interactive for humans, direct write for agents), empty-changeset rules, anti-patterns, and local verify command. Existing alpha/publishing/maintainer content is preserved below.
Cross-references updated in PR template, copilot instructions, release-docs instructions, typescript instructions, and
scripts/check-changeset-required.mjserror messages.Validation
rg "decision table below|See AGENTS\.md|AGENTS\.md changeset"— no stale referencesnode scripts/check-changeset-required.mjs --base origin/main(exit 0)Release notes / changeset
No changeset required — no public npm package files changed.
Notes
None.