菜单
Create changeset files for changes to ePDS that affect end users, client app developers, or operators. Use when adding features, changing configuration, altering OAuth flows, or any change a downstream consumer needs to adapt to.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | writing-changesets |
| description | Create changeset files for changes to ePDS that affect end users, client app developers, or operators. Use when adding features, changing configuration, altering OAuth flows, or any change a downstream consumer needs to adapt to. |
Create a changeset file to document changes for release that affect end users, client app developers, or operators.
Add a changeset when making changes that affect anyone consuming or running ePDS:
Skip changesets for:
auth-service and
pds-core (e.g. the HMAC callback signature, internal-only
routes under /_internal/). These are contributor-facing, not
consumer-facing.If in doubt, add one. An "empty" changeset (intentionally no
release) can be created with pnpm changeset add --empty to
document the decision.
ePDS changesets should call out which of the following audiences a change affects, listed in this order — from the person closest to the running software outward to the person maintaining it:
/oauth/authorize, callback handling, and anything visible at
the HTTP boundary.List only the audiences that actually need to adapt or will notice the change. Omit audiences that are not affected.
Do not list "library consumers" as an audience. The
pds-core, auth-service, and shared packages are all private
and never published to any registry; the only "consumer" of the
shared exports is ePDS itself, and that's contributor territory.
ePDS treats itself as a single release unit even though the source
is organised into packages/*. Changesets is configured to track
only the root ePDS package, so every changeset has a single
frontmatter entry and the resulting CHANGELOG is a single file at
the repo root.
Create a file in .changeset/ with a descriptive kebab-case name
(e.g. configurable-otp-length.md, handle-selection-flow.md). Do
not use the random name Changesets generates — give it a name that
reflects the change.
---
'ePDS': minor
---
One-sentence summary in the voice of the final changelog entry.
**Affects:** End users, Client app developers, Operators
Longer explanation with enough concrete detail that each listed audience can adapt their environment or code without reading the PR or source. Use concrete names, values, file paths, and example snippets where applicable. Write the per-audience sections in the same order as the `**Affects:**` line: end users first, then client app developers, then operators.
The frontmatter is always just "ePDS": <bump>. Do not list
@certified-app/pds-core, @certified-app/auth-service, or any
other package name — those packages are deliberately not tracked
by Changesets.
Bump types:
patch — bug fixes, non-breaking internal-behaviour changes
that downstream consumers can observe.minor — new features, new config options, additive API
changes. Also used for breaking changes while ePDS is still at
a 0.x.y version, following the semver-for-0.x convention.major — breaking changes, only after ePDS reaches 1.0.0.
Avoid for now.If a single changeset mixes a feature and a bug fix, pick minor
(the larger bump wins anyway when aggregated).
Every non-trivial changeset must contain, in this order:
Summary sentence — one physical line, in the voice of the final changelog entry (not a commit message).
The summary line is read by everyone listed in **Affects:**,
not just the most technical audience. It is the text that
appears in the "Who should read this release" block at the top
of the release section, and the "Who should read" block groups
bullets by audience — so End users, Client app developers, and
Operators all see the same summary line under their own
heading. Write the summary in language the least technical
listed audience can understand.
Concretely: if the changeset affects End users (even just as one of several audiences), the summary must be written in end-user language. Avoid:
OTP, DID, PAR, OAuth,
HMAC, DPoP) — spell them out or rephrase.login_hint, client_metadata,
epds_handle_mode) — the user doesn't know these exist.resolver chain, precedence,
schema validation) — describe the observable effect
instead.auth service, pds-core,
internal endpoint) — say what the user sees happening.Technical naming belongs in the per-audience sections further down, where a client-app developer or operator reading their section expects to see exact field names and env vars. The summary line is not the place for it.
Examples of the same change written badly and then well:
❌ "Configurable OTP code length and charset."
✅ "Longer sign-in codes, optionally mixing letters and numbers."
❌ "Handle selection step in the new-user signup flow."
✅ "Choose your own handle when signing up, instead of being given a random one."
❌ "Accept AT Protocol handles and DIDs as OAuth login_hint values."
✅ "Sign in faster from third-party apps that already know who you are."
If the change is purely operator-facing (no End users in the
**Affects:** line), operator language is fine in the summary
— the only audience reading it is operators.
**Affects:** line — required, comma-separated list of
audiences from the list above, in that order: End users, Client
app developers, Operators. Omit audiences that are not affected,
but never omit the **Affects:** line itself — the release
workflow fails hard if a changeset has no **Affects:** line,
because the "Who should read this release" block generation (see
below) has nothing to aggregate. If a change genuinely affects
nobody listed, it probably doesn't need a changeset at all.
Per-audience adaptation detail — one short section per
affected audience, in the same order as the **Affects:**
line, with concrete names and examples. Use bold inline
audience labels rather than headings to keep generated
changelogs readable. Inside each per-audience section you can
and should use exact technical terms that the listed audience
will recognise (env var names, field names, function names) —
the plain-language rule only applies to the summary line above.
Each paragraph in the changeset body must be unwrapped: one paragraph per physical line. Do not manually hard-wrap prose at 72 or 80 columns inside the changeset file. Wrapped source lines are preserved by GitHub and some other Markdown renderers when the release notes are rendered from generated changelog bullets, which makes the published release notes look awkwardly line-broken. Keep prose unwrapped so the rendered release notes can wrap naturally.
Do not restate the summary in the per-audience sections. The reader has already seen the summary once at the top of the bullet and once in the "Who should read this release" block. Per-audience sections should extend the summary with the information that audience specifically needs — not translate it into their vocabulary and repeat it. A useful test: if you delete the summary line and the per-audience section still makes sense as a standalone paragraph, the section was restating the summary. Rewrite it to start from what's new to that audience instead.
Do not put a "shared preamble" paragraph between the
**Affects:** line and the first per-audience section. Such
preambles are almost always either restating the summary, or
containing information that actually belongs inside one of the
per-audience sections (usually the most technical one — the
fact that you were tempted to promote it out of the section
means you were treating it as common knowledge when it isn't).
Put it inside the right section instead.
Do not use ## or ### markdown headings anywhere in the
changeset body. @changesets/changelog-github renders each
changeset as a single bullet in the release section: the first
line becomes the bullet, every subsequent line is indented by two
spaces to stay inside the list item. An indented ## will either
break out of the list (GitHub) or render as literal text (other
renderers), in both cases mangling the changelog. Use bold inline
labels (**End users:**, **Operators:**) instead. Fenced code
blocks and nested bullet lists are fine because they survive the
2-space indent cleanly.
The goal: a reader in one of the listed audiences should be able to adapt their environment or code without reading the PR or the source. Changesets are not release-note marketing copy — they are migration instructions.
"Concrete" is not "exhaustive". Include exactly what the reader needs to adapt, and stop. Most changesets are two to four sentences per audience; a small change is often a single sentence. Length must track the size of what the reader has to do, not the effort that went into the change. A one-line behaviour tweak gets a one-line changeset even if the PR was large.
Brevity and bullets are not in tension: cutting is about how many points survive, bullets are about how you lay them out so the survivors stay scannable. First cut to the points the reader must act on; then, if 3+ remain, lay them out as bullets rather than packing them into one paragraph — a short multi-point section is still a wall of text when run together. Keep one- or two-point sections as inline prose. If you find yourself writing a fourth or fifth bullet, that is a signal to cut, not to keep listing.
Before you finish, delete anything the reader does not act on:
Rule of thumb: if removing a sentence would not change what the reader does, remove it. A tight four-line changeset that names the fields and the observable effect beats a fifteen-line one that also explains the mechanism, quotes a sample, and enumerates every case.
Good adaptation detail includes:
Bad (avoid):
epds_handle_mode.It is fine to reference documentation (e.g. .env.example) for
long details, but the changeset itself must still name the thing
and describe the change. Do not offload the entire explanation.
Per-audience sections answer "what do I need to do differently" for that audience. They are not PR descriptions, design docs, or architecture overviews. Even when writing for a technical audience (Client app developers, Operators), keep the focus on the adaptation surface and resist the urge to explain how the change is implemented.
The bar to clear before including any technical detail in a per-audience section: does the reader's adaptation depend on knowing this? If they could change their config / code correctly without it, leave it out.
Avoid in per-audience sections:
pds-core mounts a pre-route guard…, the welcome-page-guard…,
auth-service's session-detection middleware…) — readers
consume ePDS as a single product, not a monorepo.upstream's request-manager.js force-overrides…, the SPA's delegated click listener…).A redirects to B which mounts C which calls D…) — these belong in
docs/design/*.md, not in release notes.…to prevent the React SPA from intercepting the click) — readers need to
know the observable contract, not the trick used to deliver
it.Useful in per-audience sections (the things readers do adapt against):
Test the section by asking: if a downstream consumer pasted this section into their team's "what changed" channel, would they know what to do, without anyone needing to ask "but what does that mean for us?" If the answer is no, the section is too implementation-flavoured.
Per-audience sections frequently end up holding 3+ distinct points (a behaviour change, a config knob, a fallback condition, a related caveat). Rendered as one wall-of-text paragraph these are hard to scan in release notes — readers skim for the points that affect them and lose them in dense prose.
When a per-audience section has 3+ distinct points, structure them as a bullet list under the bold audience label. Keep one short framing sentence on the same line as the label if useful; put each distinct point on its own bullet. One short bullet per point is much easier to scan than a long paragraph that mixes them.
Two- or one-point sections can stay as inline prose under the label — the bullet structure is for the dense case, not a mandatory shape.
Bullet lists survive the 2-space indent that
@changesets/changelog-github applies to changeset body lines
(see the ## heading restriction in Body structure above),
so they render correctly in the generated CHANGELOG.md and on
GitHub release pages.
---
'ePDS': minor
---
Longer sign-in codes, optionally mixing letters and numbers.
**Affects:** End users, Operators
**End users:** OTP codes may now be longer than 6 digits and may include uppercase letters if the operator has opted into the `alphanumeric` charset. Codes of length 8 or more are displayed with a space in the middle (e.g. `1234 5678`) for readability; copy-paste still yields the flat code.
**Operators:** two new environment variables on the auth service — `OTP_LENGTH` (integer, range 4–12, default 8) and `OTP_CHARSET` (`numeric` (default) or `alphanumeric`). Values outside the range cause the service to fail on startup. The OTP input form fields adapt automatically; no template changes required.
A denser change with several distinct points per audience is better as bullets:
---
'ePDS': minor
---
A second app sign-in in your browser now skips the email code step.
**Affects:** End users, Client app developers, Operators
**End users:**
- After signing in once, a second app asking you to sign in skips the email code step.
- You either land on the "approve this app" screen or on a chooser where you confirm which identity to reuse.
- A "Use a different account" link on the chooser takes you back to the email form.
**Client app developers:** no client-side changes required.
- When a previous sign-in's cookies are present, the user lands on the account chooser to confirm which identity to reuse.
- To force the email code form instead, set the standard OIDC `prompt` parameter to `login` on the authorization request your OAuth library sends.
**Operators:** no new required configuration.
- ePDS auto-detects whether the auth service shares a parent domain with the PDS (`AUTH_HOSTNAME` ends with `.<PDS_HOSTNAME>`) and broadens the device-session cookies to that parent. On unrelated hostnames the feature self-disables.
**Affects:** line feedsAfter changeset version runs, scripts/changelog-audience-summary.mjs
post-processes the newly-written release section of CHANGELOG.md.
For every changeset bullet it reads the **Affects:** line, groups
summaries by audience, and prepends a "Who should read this release"
block at the top of the release section. Each summary bullet in the
block is a markdown link to an HTML anchor on the corresponding
detailed entry below, so a reader can click through from their
audience to the specific adaptation instructions.
You do not need to do anything special to feed this — as long as
each changeset has a valid **Affects:** line, the block is
generated automatically on release. If a changeset omits the line,
the script fails and the release workflow stops, which is
intentional: it means "forgot to tag your changeset" is a loud,
fixable error, not silently-missing release notes.
See docs/PUBLISHING.md for how changesets are consumed at
release time and how the release workflow (manual phase 1 to open
the Release PR, automatic phase 2 to tag + publish the GitHub
Release on Release-PR merge) produces the git tag and GitHub
Release.
.changeset/config.json — Changesets configuration.package.json — the "workspaces": ["."] field is what
puts Changesets into single-package mode. See docs/PUBLISHING.md
for why this coexists with pnpm-workspace.yaml..changeset/*.md — existing changesets are the best reference
for naming and format.scripts/changelog-audience-summary.mjs — post-processor that
reads **Affects:** lines and builds the "Who should read this
release" block.docs/PUBLISHING.md — full publishing / release workflow guide..github/workflows/release.yml — the workflow that consumes
changesets.