Skip to content

Commit 15fa68c

Browse files
tylerbutlerJosmithr
tylerbutler
and
Josmithr
authored
docs: rewrite .changeset/README.md as comprehensive changeset guide (#26640)
## Summary - Rewrites `.changeset/README.md` from a brief pointer to the wiki into comprehensive, self-contained documentation covering changeset format, custom metadata, release note sections, formatting guidelines, and worked examples — consolidating information previously scattered across the wiki --------- Co-authored-by: Joshua Smithrud <54606601+Josmithr@users.noreply.github.com>
1 parent 2a8e4d6 commit 15fa68c

File tree

1 file changed

+217
-9
lines changed

1 file changed

+217
-9
lines changed

‎.changeset/README.md‎

Lines changed: 217 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,224 @@
11
# Changesets
22

3-
This folder contains changesets, which are markdown files that hold two key bits of information:
3+
We use a modified version of the [changesets][] workflow to track changes that we want to communicate to customers or partners.
44

5-
1. a version type (following semver), and
6-
2. change information to be added to a changelog. You can find the full documentation for it
7-
[in the changesets section of our wiki](https://github.com/microsoft/FluidFramework/wiki/Changesets) or in [the official changesets documentation.](https://github.com/changesets/changesets)
5+
A changeset is a Markdown file with YAML front matter stored in the `.changeset` folder. It carries two key bits of information:
86

9-
There is also a list of [frequently asked questions](https://github.com/microsoft/FluidFramework/wiki/Changesets-FAQ) in
10-
the wiki.
7+
- The packages affected by the change
8+
- A Markdown-formatted description of the change
9+
10+
This is useful because it breaks change tracking into two steps:
11+
12+
1. **Adding a changeset** — done in a PR, by a contributor, while the change is fresh in mind.
13+
2. **Releasing/versioning** — combines all changesets and writes changelogs, which can then be reviewed in aggregate.
14+
15+
## Changeset format
16+
17+
```md
18+
---
19+
"@myproject/cli": minor
20+
"@myproject/core": minor
21+
---
22+
23+
Change all the things
24+
25+
More exposition about the change.
26+
```
27+
28+
> [!NOTE]
29+
> The bump type (`major` | `minor` | `patch`) is included in every changeset, but **within the FluidFramework repo the bump type is determined by the branch the change is merged to.** Practically speaking, this means most changesets are `minor` changes. If you use the tools we provide, this metadata will be filled out for you automatically.
30+
31+
## Custom metadata
32+
33+
We support additional custom metadata via special properties prefixed with double underscores (`__`). **This is not supported by standard changeset tools**, including [@changesets/cli](https://www.npmjs.com/package/@changesets/cli); it is a custom addition used by our own tools.
34+
35+
```md
36+
---
37+
"@myproject/cli": minor
38+
"__section": fix
39+
"__includeInReleaseNotes": false
40+
"__highlight": true
41+
---
42+
43+
Change all the things
44+
```
45+
46+
All custom metadata is optional and is primarily intended to help with release notes generation:
47+
48+
- **`__section`** — the section of the release notes the entry should appear in. See [release note sections](#release-note-sections) below.
49+
- **`__includeInReleaseNotes`** — set to `false` to hide an entry from the release notes entirely.
50+
- **`__highlight`** — set to `true` to highlight an entry within its section, re-ordering it to appear first. Otherwise entries are sorted by commit date.
51+
52+
The TypeScript type for this metadata is `FluidCustomChangesetMetadata` in `build-tools/packages/build-cli/src/library/changesets.ts`.
53+
54+
> [!IMPORTANT]
55+
> Because standard changeset tools don't support custom metadata, our tools such as `flub generate:changelog` strip it before invoking commands like `changeset version`. If not removed, it ends up in changelogs and messes with formatting.
56+
57+
### Release note sections
58+
59+
The sections are configured in [fluidBuild.config.cjs](https://github.com/microsoft/FluidFramework/blob/main/fluidBuild.config.cjs) in the root of the repo. Current sections:
60+
61+
| Section | Heading | Use for |
62+
|---------------|--------------------------------|--------------------------------------------|
63+
| `breaking` | Breaking Changes | Breaking API changes (typically major releases / server only) |
64+
| `feature` | New Features | New capabilities and features |
65+
| `tree` | SharedTree DDS Changes | Changes specific to SharedTree |
66+
| `fix` | Bug Fixes | Bug fixes |
67+
| `deprecation` | Deprecations | Newly deprecated APIs |
68+
| `legacy` | Legacy API Changes | Changes to legacy/compat APIs |
69+
| `other` | Other Changes | Everything else |
70+
71+
> [!NOTE]
72+
> Client releases with breaking _legacy_ changes should use the `legacy` section, not `breaking`. The `breaking` section is reserved for major releases, which practically means server.
73+
74+
## Changesets that apply to no packages
75+
76+
Sometimes information needs to be in the release notes but doesn't apply to any package (e.g. when deleting a package). To accommodate this, we support changesets that omit package names:
77+
78+
```md
79+
---
80+
"__section": other
81+
---
82+
83+
This changeset will be included in the release notes but not per-package changelogs.
84+
```
85+
86+
> [!TIP]
87+
> Standard changeset tools silently ignore changesets that apply to no packages. This is fine since such changesets are intended for release notes only.
88+
89+
## Adding a changeset to a PR
90+
91+
You can add a changeset manually or by using the `pnpm flub changeset add` command.
92+
93+
### Using the CLI
94+
95+
Run `pnpm flub changeset add --releaseGroup <releaseGroup>` from the root of the release group. You will be prompted to select affected packages. By default the CLI shows packages changed relative to `main`; use `--branch <BRANCH>` to compare with a different branch. The output is fully editable after creation.
96+
97+
### Manually
98+
99+
Add a markdown file to the `.changeset` folder with a descriptive kebab-case name (e.g. `add-batch-operations.md`). Include the YAML frontmatter with affected packages and metadata.
100+
101+
### Empty changeset
102+
103+
Use `pnpm flub changeset add --empty` to create an empty changeset, then fill in the details.
104+
105+
### How do I know what packages to include?
106+
107+
Each package listed in a changeset will get a changelog entry with the changeset's contents. Only include packages where the change is **meaningful to consumers**. You don't need to list every package that was modified. For example, if you deprecate a class in packageA and update packageB to stop using it, only packageA needs the changeset.
108+
109+
## Formatting
110+
111+
- Each changeset needs at least two parts: a summary line (the heading) and a body paragraph.
112+
The summary can stand alone for simple changes, but a body is recommended.
113+
- The summary line should be succinct and focused on the **customer benefit** rather than the implementation.
114+
- The summary line should not have sentence punctuation (no period at the end).
115+
- The summary line should not contain code formatting (backticks).
116+
Too much code formatting in headings becomes unreadable, and there's no good way to measure "too much," so we avoid it altogether.
117+
- Write in present tense ("Add support for...") or present perfect ("Has been updated to...").
118+
We use present tense because we are describing changes in the current release.
119+
A useful rule of thumb: mentally prefix the summary with "In this release," and verify it reads naturally.
120+
- Avoid referring to package names in the summary (they appear in the "packages affected" section of release notes).
121+
- Changeset body content may include Markdown headings starting at **level 4** (`####`), since levels 1-3 are used in the release notes structure.
122+
- Include links to relevant documentation (e.g. API docs on fluidframework.com) where possible.
123+
- A changeset should never be just a link — always include a summary with links for more detail.
124+
- For features, breaking changes, and deprecations, include a code example showing usage or migration.
125+
Use `// ...` to elide boilerplate and keep examples focused on the essential change.
126+
- Wrap lines at sentence boundaries for better git diffs and review tooling.
127+
128+
### What NOT to include
129+
130+
- Internal implementation details irrelevant to consumers
131+
- PR numbers or issue references (added automatically by the changelog generator)
132+
- Author attribution
133+
- Dates (added automatically during release)
134+
- Changes to test-only or internal-only packages
135+
136+
### Examples
137+
138+
#### Bug fix
139+
140+
```md
141+
---
142+
"@fluidframework/container-runtime": minor
143+
"__section": fix
144+
---
145+
146+
Incorrect error message when disposing a container has been fixed
147+
148+
The error message when attempting to dispose a container that is already disposed now correctly identifies the operation that failed.
149+
```
150+
151+
#### New feature (tree + fluid-framework)
152+
153+
````md
154+
---
155+
"@fluidframework/tree": minor
156+
"fluid-framework": minor
157+
"__section": feature
158+
"__highlight": true
159+
---
160+
161+
Add support for schema evolution in SharedTree
162+
163+
SharedTree now supports evolving document schemas over time.
164+
When a document is opened with a newer schema version, the runtime automatically handles migration of existing data to match the new schema.
165+
166+
#### Migration behavior
167+
168+
When schema changes are detected:
169+
- New optional fields are added with default values
170+
- Removed fields are silently ignored during deserialization
171+
- Type changes follow the standard coercion rules
172+
173+
```typescript
174+
// ...
175+
const view = tree.viewWith(new TreeViewConfiguration({ schema: MyUpdatedSchema }));
176+
// ...
177+
```
178+
````
179+
180+
#### Breaking change with migration example
181+
182+
````md
183+
---
184+
"@fluidframework/container-runtime": minor
185+
"@fluidframework/container-definitions": minor
186+
"__section": breaking
187+
---
188+
189+
Deprecated summarizer options have been removed from container runtime
190+
191+
The deprecated `ISummaryOptions` interface has been removed.
192+
Use `ISummaryConfiguration` instead, which provides the same capabilities with a clearer configuration model.
193+
194+
#### Migration
195+
196+
```typescript
197+
// Before
198+
// ...
199+
const options: ISummaryOptions = { maxOps: 100 };
200+
// ...
201+
202+
// After
203+
// ...
204+
const config: ISummaryConfiguration = { maxOps: 100 };
205+
// ...
206+
```
207+
````
208+
209+
## Which PRs require changesets?
210+
211+
Any change that should be communicated to customers or partners should have a changeset. Changes without a changeset are "invisible" to customers. Add a changeset with every communicable change, even if empty — the contents can be updated before release. The presence of the changeset signals that something needs to be communicated.
212+
213+
## More information
214+
215+
- [Official changesets documentation](https://github.com/changesets/changesets)
216+
- [Changesets FAQ](https://github.com/microsoft/FluidFramework/wiki/Changesets-FAQ)
217+
- For questions, contact @tylerbutler
11218

12219
## Updating changelogs from changesets
13220

14-
See
15-
[flub generate changelog](../build-tools/packages/build-cli/docs/generate.md#flub-generate-changelog), which is built on
16-
top of [@fluid-private/changelog-generator](../build-tools/packages/changelog-generator/README.md).
221+
See [flub generate changelog](../build-tools/packages/build-cli/docs/generate.md#flub-generate-changelog), which is built on top of [@fluid-private/changelog-generator](../build-tools/packages/changelog-generator/README.md).
222+
223+
<!-- LINKS -->
224+
[changesets]: https://github.com/changesets/changesets

0 commit comments

Comments
 (0)