docs(repo): clarify changesets describe user-facing changes

[alexcarpenter]

Description

Expands the changeset rule in AGENTS.md to clarify that a changeset is a changelog entry for users upgrading the package, not a summary of the work done in the PR. It should describe the user-facing change rather than implementation details of the diff, and use an empty changeset when there is no user-facing impact.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: 12e7ed7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 2, 2026 8:08pm

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates contributor documentation in AGENTS.md to clarify changeset requirements. The change specifies that changesets must describe user-facing impact—what consumers upgrading will need to know—rather than implementation details, with guidance to use an empty changeset when there is no user-facing change. The PR includes a changeset file (bright-parrots-play.md) documenting the change itself.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Possibly related PRs

• clerk/javascript#8610: Both PRs update AGENTS.md with overlapping guidance requiring changesets to describe user-facing impact and allowing empty changesets when there is no user impact.
• clerk/javascript#8566: Directly builds on earlier changeset guidance updates by refining how changesets should communicate user-visible upgrade impact.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: clarifying that changesets should describe user-facing changes rather than implementation details.
Description check	✅ Passed	The description is directly related to the changeset, explaining the rationale and guidance for changesets as user-facing changelog entries rather than PR work summaries.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8729

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8729

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8729

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8729

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8729

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8729

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8729

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8729

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8729

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8729

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8729

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8729

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8729

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8729

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8729

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8729

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8729

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8729

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8729

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8729

commit: 12e7ed7

[coderabbitai]

🧹 Nitpick comments (1)

AGENTS.md (1)

10-10: 💤 Low value

Optional: Consider adding a concrete example for clarity.

The updated guidance is clear and comprehensive. To further strengthen contributor understanding, you could optionally add a brief inline example distinguishing user-facing vs implementation-focused changeset descriptions:

Example format:

✓ "Added support for custom error messages in signIn()"
✗ "Refactored AuthService.handleSignIn to use new ErrorHandler class"

However, given that this is a rules section and CONTRIBUTING.md is referenced for detailed guidance, the current text is already functional and actionable.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@AGENTS.md` at line 10, Add a brief concrete example to the changeset guidance
showing a user-facing description vs an implementation-focused one to clarify
intent; update the paragraph that references `pnpm changeset` / `pnpm
changeset:empty` (the changeset guidance) by appending a one-line good example
and one-line bad example illustrating the difference (e.g., a consumer-facing
change like "Added support for custom error messages in signIn()" versus an
implementation note like "Refactored AuthService.handleSignIn to use new
ErrorHandler class"), so contributors can quickly see the expected phrasing when
creating a changeset.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@AGENTS.md`:
- Line 10: Add a brief concrete example to the changeset guidance showing a
user-facing description vs an implementation-focused one to clarify intent;
update the paragraph that references `pnpm changeset` / `pnpm changeset:empty`
(the changeset guidance) by appending a one-line good example and one-line bad
example illustrating the difference (e.g., a consumer-facing change like "Added
support for custom error messages in signIn()" versus an implementation note
like "Refactored AuthService.handleSignIn to use new ErrorHandler class"), so
contributors can quickly see the expected phrasing when creating a changeset.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: c7d2fd17-eb6d-49dc-ae9e-ff4e8a605e9c

📥 Commits

Reviewing files that changed from the base of the PR and between c2ba134 and 12e7ed7.

📒 Files selected for processing (2)

• .changeset/bright-parrots-play.md
• AGENTS.md

[wobsoriano]

💯

[jacekradko]

💯