[READ-ONLY] Mirror of https://github.com/bombshell-dev/tools. Internal CLI to standardize tooling across all Bombshell projects
feat(skills): add docs skills
Nate Moore
(May 2, 2026, 5:52 PM EDT)
fcc4451b
677b2e0d
+740
+264
skills/writing-changesets/SKILL.md
+264
skills/writing-changesets/SKILL.md
···
1
+
---
2
+
name: writing-changesets
3
+
description: >
4
+
Writing user-facing CHANGELOG entries with the Changesets tool — `.changeset/*.md`
5
+
files declaring affected packages, bump kind (patch/minor/major), and a message.
6
+
Covers verb choice, audience, level of detail, and breaking-change migration
7
+
patterns with diff samples. Use when adding a changeset to a PR.
8
+
---
9
+
10
+
# Writing Changesets
11
+
12
+
A changeset is a Markdown file that declares **which packages changed**, **how to bump them**, and **what changed from the user's perspective**. It produces one entry in each affected package's CHANGELOG.
13
+
14
+
A user reads a changeset once, when they upgrade. It must answer: _did anything change that matters to me, and what do I do about it?_
15
+
16
+
## File format
17
+
18
+
Generate a changeset with:
19
+
20
+
```sh
21
+
pnpm changeset
22
+
```
23
+
24
+
This prompts for the affected packages and bump kinds, then writes a randomly-named file to `.changeset/`:
25
+
26
+
```md title=".changeset/witty-cats-bake.md"
27
+
---
28
+
"@your-org/your-package": patch
29
+
---
30
+
31
+
Fixes a regression where `parseConfig()` returned `undefined` instead of the default object.
32
+
```
33
+
34
+
You can also write the file by hand. The frontmatter lists every affected package on its own line:
35
+
36
+
```md title=".changeset/multi-package-change.md"
37
+
---
38
+
"@your-org/core": minor
39
+
"@your-org/cli": patch
40
+
---
41
+
42
+
Adds a new `--watch` flag.
43
+
44
+
#### `@your-org/core`
45
+
46
+
Exports a new `watch()` helper.
47
+
48
+
#### `@your-org/cli`
49
+
50
+
Wires `--watch` to call `watch()`.
51
+
```
52
+
53
+
Bump kinds:
54
+
55
+
- `patch` — bug fixes, internal refactors, perf improvements (no user code change required)
56
+
- `minor` — new features that are safe to opt into
57
+
- `major` — breaking changes, including any change to default behavior
58
+
59
+
## The message
60
+
61
+
### Lead with a present-tense verb
62
+
63
+
Every changeset starts with a verb completing the sentence "This PR…":
64
+
65
+
- **Adds** — new feature, option, function
66
+
- **Removes** — deletes a public API
67
+
- **Fixes** — bug fix
68
+
- **Updates** — changes existing behavior in a non-breaking way
69
+
- **Refactors** — internal cleanup
70
+
- **Improves** — perf, ergonomics, output quality
71
+
- **Deprecates** — marks something for future removal
72
+
73
+
### Describe the user's experience, not the code's
74
+
75
+
❌ What the code now does:
76
+
77
+
> Logs helpful errors if content is invalid
78
+
79
+
✅ What the user will experience:
80
+
81
+
> Adds logging for content collection configuration errors
82
+
83
+
The reader doesn't care what the diff did internally. They care what they'll notice.
84
+
85
+
### Include the API name when readers might be using it
86
+
87
+
When the changed surface has a recognizable name, put it in the message:
88
+
89
+
❌ Vague:
90
+
91
+
> Improves automatic fallback generation
92
+
93
+
✅ Specific:
94
+
95
+
> Improves automatic `fallbacks` generation for the new Fonts API
96
+
97
+
If the API isn't user-facing or the name wouldn't ring a bell, describe the use case instead:
98
+
99
+
❌ Reader won't recognize the type:
100
+
101
+
> Adds `| (string & {})` for better autocomplete of `App.SessionData`
102
+
103
+
✅ Reader recognizes the outcome:
104
+
105
+
> Improves autocompletion for session keys
106
+
107
+
## Patch changes
108
+
109
+
Patch changes are usually internal: bug fixes, refactors, perf wins. The reader skims to decide if it's relevant.
110
+
111
+
Keep them short — often one line:
112
+
113
+
```md title=".changeset/one-liner.md"
114
+
---
115
+
"@your-org/core": patch
116
+
---
117
+
118
+
Fixes a bug where the inspector incorrectly flagged inline images as above the fold
119
+
```
120
+
121
+
```md title=".changeset/refactor.md"
122
+
---
123
+
"@your-org/core": patch
124
+
---
125
+
126
+
Refactors internal handling of styles and scripts to improve build performance
127
+
```
128
+
129
+
```md title=".changeset/type-update.md"
130
+
---
131
+
"@your-org/core": patch
132
+
---
133
+
134
+
Updates the `HTMLAttributes` type exported from `@your-org/core` to allow data attributes
135
+
```
136
+
137
+
Patch entries don't need full sentences or end punctuation when they fit on one line. State **what changed** _and_ **who needs to know** — the reader should be able to decide in five seconds whether to keep reading.
138
+
139
+
## Minor changes (new features)
140
+
141
+
Start with **Adds**. Name the new option, function, or component in the first sentence. Then say what users can now do that they couldn't before.
142
+
143
+
````md title=".changeset/new-feature.md"
144
+
---
145
+
"@your-org/core": minor
146
+
---
147
+
148
+
Adds a new, optional `timeout` option to `defer()`.
149
+
150
+
This value sets a maximum wait, in milliseconds, before the deferred work is flushed, even if the trigger condition hasn't been met. You can use it to bound the latency of low-priority work while still preferring the natural flush point.
151
+
152
+
```ts
153
+
defer(work, { trigger: "idle", timeout: 500 });
154
+
```
155
+
````
156
+
157
+
A minimal usage example is almost always worth including for new features. Don't try to cover every option — pick one realistic call.
158
+
159
+
> **Don't hide the good stuff in the changeset.** A changeset is read once, on upgrade. Documentation is referenced forever. Everything you put in a changeset should also exist in the proper feature docs.
160
+
161
+
## Major changes (breaking)
162
+
163
+
Verbs like **Removes**, **Changes**, **Deprecates** signal _required attention_. Unlike a new feature the reader can ignore, a breaking change cannot be skipped.
164
+
165
+
A breaking-change changeset must include **migration guidance**, almost always with a `diff` code sample:
166
+
167
+
```md title=".changeset/breaking-removal.md"
168
+
---
169
+
"@your-org/core": major
170
+
---
171
+
172
+
Removes support for returning plain objects from endpoints. Endpoints must now return a `Response` instead.
173
+
```
174
+
175
+
For an API rename or signature change, show the before and after:
176
+
177
+
````md title=".changeset/breaking-shape-change.md"
178
+
---
179
+
"@your-org/core": major
180
+
---
181
+
182
+
Removes support for passing a `path` string to the `plugins` option. Import the plugin module directly and pass it instead.
183
+
184
+
```diff
185
+
+ import customPlugin from './plugins/custom.js'
186
+
187
+
export default defineConfig({
188
+
plugins: [
189
+
- { path: './plugins/custom.js' },
190
+
+ customPlugin,
191
+
],
192
+
})
193
+
```
194
+
````
195
+
196
+
### Default-value changes
197
+
198
+
Changing a default value is a breaking change even if no API surface moved — most users don't set a value explicitly, so they're affected silently.
199
+
200
+
Document **both directions**: how to opt back into the old behavior, _and_ the fact that anyone who already set the new value can drop it.
201
+
202
+
````md title=".changeset/default-flip.md"
203
+
---
204
+
"@your-org/core": major
205
+
---
206
+
207
+
Changes the default value of `security.checkOrigin` to `true`, enabling CSRF protection by default for on-demand pages.
208
+
209
+
If you previously set `security.checkOrigin: true`, you no longer need it — this is now the default and the line can be removed.
210
+
211
+
To restore the previous behavior, set `security.checkOrigin: false` explicitly:
212
+
213
+
```diff
214
+
export default defineConfig({
215
+
+ security: {
216
+
+ checkOrigin: false
217
+
+ }
218
+
})
219
+
```
220
+
````
221
+
222
+
## Section headings inside long changesets
223
+
224
+
When a changeset spans multiple paragraphs and needs internal structure, **start headings at `<h4>` (`####`)** — never `<h2>`. Changesets are concatenated into a CHANGELOG file where the package name and version are already at the `<h2>`–`<h3>` level. Using `##` inside a changeset breaks the hierarchy of the rendered CHANGELOG.
225
+
226
+
```md title=".changeset/long-feature.md"
227
+
---
228
+
"@your-org/core": minor
229
+
---
230
+
231
+
Adds a new Sessions API to store user state between requests for on-demand pages.
232
+
233
+
#### Configuring session storage
234
+
235
+
…
236
+
237
+
#### Using sessions
238
+
239
+
…
240
+
241
+
##### In API endpoints
242
+
243
+
…
244
+
245
+
#### Upgrading from the experimental API
246
+
247
+
…
248
+
```
249
+
250
+
## Quick checklist before merging
251
+
252
+
- [ ] Frontmatter lists every affected package with the right bump kind
253
+
- [ ] Message starts with a present-tense verb (Adds, Removes, Fixes…)
254
+
- [ ] Describes the user-facing change, not internal mechanics
255
+
- [ ] Names the changed API when the name is recognizable
256
+
- [ ] Breaking change? Includes a `diff` migration sample
257
+
- [ ] Default-value change? Documents both the new behavior and the opt-out
258
+
- [ ] Section headings (if any) start at `####`
259
+
- [ ] The same explanation also exists in proper feature docs
260
+
261
+
## See Also
262
+
263
+
- `writing-docs/SKILL.md` — voice, code-sample, and instruction conventions used here
264
+
- `writing-upgrade-guides/SKILL.md` — for major releases, breaking-change changesets feed into the upgrade guide
+259
skills/writing-docs/SKILL.md
+259
skills/writing-docs/SKILL.md
···
1
+
---
2
+
name: writing-docs
3
+
description: >
4
+
Voice, style, structure, and code-sample conventions for user-facing software
5
+
documentation — guides, reference pages, READMEs, recipes, API docs. Establishes
6
+
the imperative instruction pattern, the "what to document vs. omit" rules, and
7
+
the reference-entry format. Use when writing or reviewing prose docs.
8
+
---
9
+
10
+
# Writing Docs
11
+
12
+
Docs exist to **help readers do something and get back to their project**. Document **how to use** the thing — not how the thing is built.
13
+
14
+
## Purpose
15
+
16
+
Every page should answer questions a real reader has:
17
+
18
+
- What is this?
19
+
- What is it used for?
20
+
- Why would I use it?
21
+
- When can it (not) be used?
22
+
- How do I use it?
23
+
24
+
Implementation details only belong if they help the reader **make decisions**: choose a non-default value, avoid a conflicting setting, understand a tradeoff. Otherwise, leave them out.
25
+
26
+
## Voice and tone
27
+
28
+
- **Neutral, factual, direct.** State facts; don't try to be funny, whimsical, or chatty.
29
+
- **No first person.** Never `I`, `we`, `us`, `our`, `let's`. You aren't sitting next to the reader.
30
+
- **Address the reader as "you"** — sparingly, for emphasis or warnings. Most instructions don't need it (use the imperative instead).
31
+
- **Document only your thing.** Link out to authoritative sources for general concepts (Markdown, HTTP, regex). It is not your job to teach them.
32
+
- **Use exclamation points sparingly.** A frustrated reader at 2am does not want vibes.
33
+
34
+
## Readability heuristics
35
+
36
+
Prefer:
37
+
38
+
- shorter sentences and paragraphs
39
+
- plainer vocabulary
40
+
- active voice
41
+
- writing acronyms in full the first time
42
+
- headings and lists to break up long stretches of prose
43
+
44
+
Many readers are tired, in a hurry, reading in a non-native language, or translating the page into another language. Clear writing helps every one of them.
45
+
46
+
## Headings
47
+
48
+
- Page title is `<h1>`. New sections start at `<h2>`.
49
+
- Keep headings short — they appear in the page sidebar / table of contents.
50
+
- No end punctuation (`:`, `.`, `?`).
51
+
- Format code-shaped names as inline code, even in headings: `### \`navigate()\``.
52
+
53
+
## Lists
54
+
55
+
- **Unordered** for a group of related items where order doesn't matter (a set of options, properties, examples).
56
+
- **Ordered** when the steps must be followed in sequence.
57
+
- When list items grow into multiple paragraphs or are loaded with inline code, switch to subheadings.
58
+
59
+
## "Examples" vs. complete sets
60
+
61
+
`e.g.` means **some, not all**:
62
+
63
+
> If you store your project on a Git provider (e.g. GitHub, GitLab), you can…
64
+
65
+
When the list is **every possibility**, drop `e.g.`:
66
+
67
+
> Include the required image properties (`src`, `alt`) and any optional properties…
68
+
69
+
## Giving instructions
70
+
71
+
Use the **imperative**:
72
+
73
+
> Run the following command.
74
+
75
+
Not:
76
+
77
+
> ❌ Let's run the following command.
78
+
> ❌ Next, we will run the following command.
79
+
80
+
### Avoid weasel words
81
+
82
+
| Phrase | Problem | When it's OK |
83
+
| ------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
84
+
| "You should…" | Reader can't tell if it's required | Describing expected outcome: "If installation succeeds, you should see a prompt" — and even then, prefer "After a successful install, there will be a prompt" |
85
+
| "You can…" | Sounds permissive, not directive | Genuinely granting permission or stating an option exists |
86
+
87
+
If you find yourself writing "you should" in a step the reader is meant to follow, rewrite it as a direct instruction.
88
+
89
+
### No narrative scaffolding
90
+
91
+
Lead with the goal, then the steps. Don't tell a story.
92
+
93
+
❌ Narrative:
94
+
95
+
> As well as needing your content in different languages, you will often need to translate labels for UI elements around your site. We can do this by creating dictionaries of terms instead of hard-coding text in one language in our templates.
96
+
>
97
+
> 1. …
98
+
99
+
✅ Imperative + reason:
100
+
101
+
> Create dictionaries of terms to translate UI labels. This lets visitors experience your site fully in their language.
102
+
>
103
+
> 1. …
104
+
105
+
### Opinionated examples
106
+
107
+
When an instruction has many valid choices, separate the **action + criteria** from the **chosen option**:
108
+
109
+
❌ Vague:
110
+
111
+
> Add the `LanguagePicker` component to your site. A good place might be in a navigation component or a footer shown on every page.
112
+
113
+
✅ Action with criteria, then opinionated choice:
114
+
115
+
> Add the `LanguagePicker` component to a layout shown on every page. The example below adds it to the page footer:
116
+
117
+
The reader can substitute their own choice once they understand the criterion.
118
+
119
+
## Code samples
120
+
121
+
Code samples carry as much weight as the prose around them.
122
+
123
+
### Always include a sample file name
124
+
125
+
The reader needs to know **where this code goes**. Use a code-block title or a top-line comment:
126
+
127
+
````markdown
128
+
```ts title="src/lib/auth.ts"
129
+
export function signIn() {
130
+
/* … */
131
+
}
132
+
```
133
+
````
134
+
135
+
````markdown
136
+
```ts
137
+
// src/lib/auth.ts
138
+
export function signIn() {
139
+
/* … */
140
+
}
141
+
```
142
+
````
143
+
144
+
### Show one real, working example — not all options
145
+
146
+
No `foo` / `bar`. No "here are all six possible values for this config." The reader will only configure one. Pick a realistic one and show it complete.
147
+
148
+
### Introduce every code sample with a sentence
149
+
150
+
On its own line, before the block:
151
+
152
+
> The following example shows the `base` config set so the project deploys at `www.example.com/docs`:
153
+
154
+
This forces you to name what the snippet demonstrates and primes the reader to recognize it. Avoid `like so:` — it's a substitute for explaining what to do, and the reader's natural follow-up is "like _how_?"
155
+
156
+
❌
157
+
158
+
> Add slide animation, like so:
159
+
160
+
✅
161
+
162
+
> The following example shows a `slide` animation attribute added to a `<header>` component:
163
+
164
+
### Multiple code samples
165
+
166
+
Don't dump three blocks and explain them all in a paragraph below — readers will already have skimmed past. Introduce each block individually and connect them only after each has been described:
167
+
168
+
> The following example shows `draft: true` configured in the project config, which prevents draft posts from being built:
169
+
>
170
+
> ```js
171
+
> // …config sample
172
+
> ```
173
+
>
174
+
> The following Markdown file uses the `draft` property in its frontmatter to mark a post as not ready to publish:
175
+
>
176
+
> ```md
177
+
> // …frontmatter sample
178
+
> ```
179
+
180
+
## Reference entries
181
+
182
+
Reference pages exist to be **scanned**, not read. Each entry has a fixed shape.
183
+
184
+
### Format
185
+
186
+
```markdown
187
+
### `propertyOrFunctionName`
188
+
189
+
**Type:** `string | undefined`
190
+
**Default:** `'auto'`
191
+
**Added in:** `v1.4.0`
192
+
193
+
[One-sentence definition: what is this / what does this do.]
194
+
195
+
[Possible values, when applicable, as a bulleted list.]
196
+
197
+
[A minimal real-world code example.]
198
+
```
199
+
200
+
### Definition
201
+
202
+
The first line answers "What is this?" or "What does this do?" with an unwritten "This is…" or "This…" prefix:
203
+
204
+
- An array of allowed hosts.
205
+
- The base path to deploy to.
206
+
- Specifies the output target for builds.
207
+
- Enables CSRF protection for on-demand pages.
208
+
209
+
### Values
210
+
211
+
When the field accepts a small set of options, enumerate them:
212
+
213
+
- `'always'` — only match URLs with a trailing slash
214
+
- `'never'` — only match URLs without a trailing slash
215
+
- `'ignore'` — match URLs regardless
216
+
217
+
### Example
218
+
219
+
Show a single configured value, not every possibility:
220
+
221
+
```js
222
+
{
223
+
trailingSlash: "always";
224
+
}
225
+
```
226
+
227
+
### Don't write a "why" essay
228
+
229
+
Reference entries are concise. Save the "when would I use this?" prose for guides — link from the entry when the topic genuinely needs explanation.
230
+
231
+
## Asides / callouts
232
+
233
+
Use sparingly. A callout for note, tip, or caution is for **complementary information that does not belong in the surrounding paragraph** — not for emphasis on essential information.
234
+
235
+
| Variant | Use for |
236
+
| ----------- | ------------------------------------------------- |
237
+
| **note** | tangential context |
238
+
| **tip** | optional action that may help |
239
+
| **caution** | risk of data loss, security, or other real danger |
240
+
241
+
Don't use:
242
+
243
+
- A **note** to add essential information — that belongs in the paragraph.
244
+
- A **tip** for a required step — that's not a tip, it's a requirement.
245
+
- A **caution** for mild surprises.
246
+
- Multiple callouts in a row — visual clutter erases meaning.
247
+
248
+
If everything is highlighted, nothing is.
249
+
250
+
## What NOT to document
251
+
252
+
- **Implementation details that don't change how the user uses the feature.** "We filter the array internally" tells the reader nothing they can act on.
253
+
- **Unsupported or off-happy-path uses.** "You can do this, but I wouldn't recommend it" — don't lead the reader down a dangerous path. They are free to explore on their own.
254
+
- **Every possible combination of options.** Document the common path and the realistic decision points. Edge cases live in issues, discussions, or recipes.
255
+
256
+
## See Also
257
+
258
+
- `writing-changesets/SKILL.md` — per-change CHANGELOG entries (uses the voice and code-sample patterns from this skill)
259
+
- `writing-upgrade-guides/SKILL.md` — major-version migration guides (uses the imperative-instruction and diff-sample patterns from this skill)
+217
skills/writing-upgrade-guides/SKILL.md
+217
skills/writing-upgrade-guides/SKILL.md
···
1
+
---
2
+
name: writing-upgrade-guides
3
+
description: >
4
+
Authoring a major-version upgrade guide or breaking-change migration document.
5
+
Covers the standard guide structure, the per-entry format (past-tense before /
6
+
present-tense after / "What should I do?"), verb choice by user impact, and
7
+
diff-sample patterns. Use when shipping a major release or any document whose
8
+
job is to walk users through breaking changes.
9
+
---
10
+
11
+
# Writing Upgrade Guides
12
+
13
+
An upgrade guide is a comprehensive, action-oriented list of **breaking changes a user must address to upgrade successfully**. It is not a feature showcase, not a release announcement, and not a CHANGELOG.
14
+
15
+
If a change doesn't block an existing project from upgrading, it doesn't belong here.
16
+
17
+
## Standard structure
18
+
19
+
Major-version upgrade guides follow a fixed structure. Use it as a template:
20
+
21
+
1. **Upgrade instructions** — the automated tool (e.g. an upgrade CLI), then manual steps for users who prefer it
22
+
2. **"Things may just work — if not, read on"** — set expectations: most projects upgrade cleanly
23
+
3. **Link to the full CHANGELOG** — for readers who want every detail
24
+
4. **Experimental flags removed** — list flags from `experimental:` config that are now stable or gone
25
+
5. **Dependency upgrades** — minimum runtime / engine / peer-dep versions that may affect projects
26
+
6. **Breaking changes** — the bulk of the guide
27
+
7. **Deprecations** — features that still work but will be removed in a future version
28
+
8. **Previously deprecated features now removed** — features deprecated in earlier versions that are gone now
29
+
9. **Community resources** — videos, blog posts, codemods (if any)
30
+
10. **Known issues** — anything users will hit that isn't fixed yet
31
+
32
+
Each section can be empty. Don't pad — if there are no deprecations this release, omit the heading.
33
+
34
+
## Per-entry format
35
+
36
+
Every entry under **Breaking changes** follows the same shape.
37
+
38
+
```markdown
39
+
### [verb]: feature/area name
40
+
41
+
In vX.x, [past-tense statement of what the library used to do].
42
+
43
+
vY.0 [present-tense statement of how the library works now].
44
+
45
+
#### What should I do?
46
+
47
+
[Imperative actions, often with a diff code sample.]
48
+
```
49
+
50
+
### Title verbs
51
+
52
+
Pick the verb by **how the user feels the impact**, not by what the code change technically is.
53
+
54
+
| Verb | Use when |
55
+
| ------------ | ------------------------------------------------------------------ |
56
+
| `Changed` | Behavior, signature, or shape moved in a way the user can feel |
57
+
| `Renamed` | An identifier — option, function, file — has a new name |
58
+
| `Removed` | A public API is gone |
59
+
| `Added` | A new behavior is now the default — the reader is "newly affected" |
60
+
| `Deprecated` | Still works for now, but slated for removal |
61
+
62
+
A new default value _is_ `Changed: default value for X`, even though the underlying code "added" something. Title from the reader's seat: "my default value got switched on me."
63
+
64
+
### The body
65
+
66
+
Two short statements: **what it was**, **what it is now**:
67
+
68
+
```markdown
69
+
### Changed: `app.render()` signature
70
+
71
+
In v3.x, the `app.render()` method accepted `routeData` and `locals` as separate, optional arguments.
72
+
73
+
v4.0 changes the `app.render()` signature. Both properties are now passed as a single object. Both the object and the properties remain optional.
74
+
```
75
+
76
+
That's it. No motivation essay. No anecdote. The reader is in a hurry — they want to know whether they're affected and what to do.
77
+
78
+
### "What should I do?"
79
+
80
+
This section is the heart of the guide. It is **always present**, even when the answer is short.
81
+
82
+
The instruction must be an **action**, not a fact:
83
+
84
+
❌ Statement of fact:
85
+
86
+
> The minimum supported runtime version is now 22.x.
87
+
88
+
✅ Imperative action:
89
+
90
+
> Check your runtime version with `node --version`. If it's below 22.x, upgrade to a supported version before installing.
91
+
92
+
Whenever the user must edit code, include a **diff** sample:
93
+
94
+
````markdown
95
+
#### What should I do?
96
+
97
+
If you maintain an adapter, the previous signature continues to work until the next major version.
98
+
99
+
To migrate now, pass `routeData` and `locals` as properties of an object instead of as separate arguments:
100
+
101
+
```diff
102
+
- app.render(request, routeData, locals)
103
+
+ app.render(request, { routeData, locals })
104
+
```
105
+
````
106
+
107
+
For deprecations, state the **migration window** so users know they have time:
108
+
109
+
> The `oldOption` is still honored in vY.0 and will be removed in vZ.0. Replace it with `newOption` at your convenience.
110
+
111
+
## Worked examples
112
+
113
+
### Example 1: signature change
114
+
115
+
````markdown
116
+
### Changed: `parseConfig()` signature
117
+
118
+
In v2.x, `parseConfig()` accepted a string path and returned a parsed config synchronously.
119
+
120
+
v3.0 makes `parseConfig()` async and accepts either a path or a `URL`. It now returns a `Promise<Config>`.
121
+
122
+
#### What should I do?
123
+
124
+
Await the result and update any callers:
125
+
126
+
```diff
127
+
128
+
- const config = parseConfig('./project.toml')
129
+
130
+
* const config = await parseConfig('./project.toml')
131
+
```
132
+
````
133
+
134
+
### Example 2: default-value change with opt-out
135
+
136
+
````markdown
137
+
### Changed: default value for `security.checkOrigin`
138
+
139
+
In v4.x, `security.checkOrigin` defaulted to `false`.
140
+
141
+
v5.0 changes the default to `true`, enabling CSRF protection for on-demand pages by default.
142
+
143
+
#### What should I do?
144
+
145
+
If you previously set `security.checkOrigin: true` explicitly, you can remove it — that's now the default.
146
+
147
+
To preserve the previous behavior, set `security.checkOrigin: false` explicitly:
148
+
149
+
```diff
150
+
export default defineConfig({
151
+
152
+
- security: {
153
+
- checkOrigin: false
154
+
- }
155
+
})
156
+
```
157
+
````
158
+
159
+
### Example 3: rewriting a fact-as-statement
160
+
161
+
❌ Useless:
162
+
163
+
```markdown
164
+
### Changed: minimum runtime version
165
+
166
+
The minimum supported runtime is now 22.x.
167
+
168
+
#### What should I do?
169
+
170
+
The minimum supported runtime is now 22.x.
171
+
```
172
+
173
+
✅ Action:
174
+
175
+
````markdown
176
+
### Changed: minimum runtime version
177
+
178
+
In v4.x, runtimes 18.x and newer were supported.
179
+
180
+
v5.0 requires 22.x or newer.
181
+
182
+
#### What should I do?
183
+
184
+
Check your installed version:
185
+
186
+
`sh
187
+
node --version
188
+
`
189
+
190
+
If it reports below 22.x, install a supported version before upgrading. Most version managers (e.g. fnm, nvm, volta) can install 22.x in one command.
191
+
````
192
+
193
+
## What does NOT belong in the upgrade guide
194
+
195
+
- **New optional features.** A feature the reader can ignore does not block upgrading. It belongs in the CHANGELOG, the release blog post, or proper feature docs — not here.
196
+
- **Internal refactors.** If nothing about the user-facing API changed, leave it out.
197
+
- **Bug fixes.** Same — the CHANGELOG covers these.
198
+
- **Lengthy "why" essays.** Save the rationale for a blog post. The guide exists to get the reader unblocked.
199
+
200
+
If you find yourself writing entries that don't have a "What should I do?" answer, they probably don't belong in the guide.
201
+
202
+
## Quick checklist
203
+
204
+
- [ ] Standard sections in order (or omitted when empty)
205
+
- [ ] Every breaking change has its own `###` entry
206
+
- [ ] Each entry's title verb reflects user impact, not code mechanics
207
+
- [ ] Body has two short statements: past behavior, present behavior
208
+
- [ ] "What should I do?" exists for every entry
209
+
- [ ] Imperative actions, not statements of fact
210
+
- [ ] `diff` sample included whenever the user must edit code
211
+
- [ ] Default-value changes show both directions (new default + opt-out)
212
+
- [ ] No new-feature announcements, no bug-fix entries
213
+
214
+
## See Also
215
+
216
+
- `writing-docs/SKILL.md` — imperative-instruction and code-sample conventions used here
217
+
- `writing-changesets/SKILL.md` — breaking-change changesets feed into this guide; the per-change content is often the source material for an upgrade-guide entry