snapshot of https://github.com/tldraw/tldraw.git (main, 2026-09-23; blobs > 131072B omitted)

skills/shared/release-notes-guide.md

@@ -0,0 +1,281 @@
+# Release notes style guide
+
+This document defines the rules and conventions for tldraw SDK release notes articles in `apps/docs/content/releases/`.
+
+**Prerequisite**: Read the [voice and style guide](../../VOICE.md) first. This document builds on those foundations with release-notes-specific patterns.
+
+## Editorial guidance
+
+### What to include
+
+- Breaking changes that require user action
+- New features that solve common pain points
+- API additions that unlock new capabilities
+- Changes that affect how developers integrate tldraw
+- Bug fixes for user-reported issues
+
+### What to omit
+
+- Internal performance optimizations (unless user-visible)
+- Fixes for bugs introduced in the same release cycle
+- Implementation details that don't affect public API
+- Pure code quality improvements
+
+### When to create a featured section
+
+Promote changes to the "What's new" section when:
+
+- It's a breaking change requiring a migration guide
+- It introduces a major new capability
+- It is an interesting or significant new feature, possibly the result of multiple PRs
+- Users need detailed guidance (migration guides, platform tables)
+
+Featured sections should include:
+
+- Clear description of what changed and why it matters
+- Code examples where helpful
+- Migration guides in collapsible `<details>` blocks for breaking changes
+- Links to relevant documentation
+
+## PR categorization
+
+| Category     | Labels                       | Indicators                       |
+| ------------ | ---------------------------- | -------------------------------- |
+| API changes  | `api`, `feature`, `major`    | Adds/removes/modifies public API |
+| Improvements | `improvement`, `enhancement` | Enhances existing functionality  |
+| Bug fixes    | `bugfix`, `bug`,             | Fixes issues                     |
+
+Look for `### Release notes` and `### API changes` sections in PR bodies. Search for "breaking" to identify breaking changes. Search for "deprecat" to identify deprecated APIs (mark with 🔜, not 💥).
+
+### PRs to skip
+
+Skip PRs with these labels:
+
+- `other`
+- `skip-release`
+- `chore`
+- `dotcom`
+
+Also skip:
+
+- Reverts, unless they fix something user-facing
+- Fixes for bugs introduced in the same release cycle (i.e., the bug was caused by a PR that is also in `next.mdx` and was not in the previous release)
+
+When a PR is reverted, also remove the original PR's entry from `next.mdx` if it is present.
+
+## Team members (do not credit)
+
+angrycaptain19, AniKrisn, ds300, kaneel, kostyafarber, max-dra, mimecuvalo, MitjaBezensek, profdl, Siobhantldraw, steveruizok, tldrawdaniel, danieljamesross, jsscclr, frolic, huppy-bot, github-actions, Somehats, todepond, Taha-Hassan-Git, alex-mckenna-1, max-drake, m31-galaxy, meg-an31
+
+Credit community contributors with:
+
+```markdown
+(contributed by [@username](https://github.com/username))
+```
+
+## General notes
+
+- Do not include AI attribution
+- Write as if the release has already happened
+- Omit empty sections
+- The release listing is maintained in `apps/docs/content/getting-started/releases.mdx`
+
+---
+
+## Formatting conventions
+
+### Section order
+
+Use these sections in order (omit empty sections):
+
+1. **Introduction paragraph** - 1-2 sentence summary of the release highlights
+2. **What's new** (`## What's new`) - Featured sections (H3s) for major features and breaking changes
+3. **API changes** (`## API changes`) - New methods, properties, options, deprecations, and breaking changes
+4. **Improvements** (`## Improvements`) - Enhancements to existing functionality
+5. **Bug fixes** (`## Bug fixes`) - Fixed issues
+6. **Patch releases** (`## Patch releases`) - Separated by `---`, contains bulleted changes for each patch version
+
+### Introduction paragraph
+
+Start each release with a 1-2 sentence summary highlighting the most significant changes. Lead with concrete features, then mention infrastructure and performance:
+
+```markdown
+This release introduces several significant changes: a new pattern for defining custom shape/binding typings, pluggable storage for `TLSocketRoom` with a new SQLite option, reactive `editor.inputs`, and optimized draw shape encoding. It also adds various other API improvements, performance optimizations, and bug fixes.
+```
+
+### Entry format
+
+Start entries with a verb: "Add", "Fix", "Improve", "Remove". Keep descriptions concise but informative.
+
+```markdown
+- Add `Editor.newMethod()` for doing something useful. ([#7123](https://github.com/tldraw/tldraw/pull/7123))
+```
+
+For multiple related PRs:
+
+```markdown
+- Improve arrow snapping performance. ([#7145](https://github.com/tldraw/tldraw/pull/7145), [#7150](https://github.com/tldraw/tldraw/pull/7150))
+```
+
+With code examples:
+
+````markdown
+- Add `localStorageAtom` to `@tldraw/state`. ([#6876](https://github.com/tldraw/tldraw/pull/6876))
+
+  ```tsx
+  const myAtom = localStorageAtom('my-key', defaultValue)
+  ```
+````
+
+### Breaking changes
+
+Mark breaking API changes with a 💥 prefix. Mark deprecations (APIs that still work but will be removed in a future release) with a 🔜 prefix. Place breaking changes at the top of the API changes section, followed by deprecations:
+
+```markdown
+## API changes
+
+- 💥 **`ShapeUtil.canEdit()`** signature changed to accept a `TLEditStartInfo` parameter. ([#7361](https://github.com/tldraw/tldraw/pull/7361))
+- 💥 **`oldMethod`** renamed to `newMethod`. ([#7400](https://github.com/tldraw/tldraw/pull/7400))
+- 🔜 **`Editor.legacyMethod()`** is deprecated. Use `Editor.newMethod()` instead. ([#7450](https://github.com/tldraw/tldraw/pull/7450))
+- Add `Editor.newMethod()` for doing something useful. ([#7123](https://github.com/tldraw/tldraw/pull/7123))
+```
+
+### What's new section
+
+The `## What's new` section contains featured subsections (H3s) for headline features and major breaking changes.
+
+**Basic structure:**
+
+```markdown
+## What's new
+
+### Feature name ([#7320](https://github.com/tldraw/tldraw/pull/7320))
+
+Brief description of what this feature does and why it matters.
+```
+
+**Multiple related PRs:**
+
+```markdown
+### Pluggable storage for TLSocketRoom ([#7320](https://github.com/tldraw/tldraw/pull/7320), [#7123](https://github.com/tldraw/tldraw/pull/7123))
+```
+
+**Deprecation featured sections** - add 🔜 to the heading:
+
+```markdown
+### 🔜 Deprecation of old API ([#0000](https://github.com/tldraw/tldraw/pull/0000))
+
+Brief description of what is deprecated and what to use instead.
+```
+
+**Breaking change featured sections** - add 💥 to the heading and include a migration guide:
+
+```markdown
+### 💥 Feature name ([#0000](https://github.com/tldraw/tldraw/pull/0000))
+
+Brief description of what this feature does and why it matters.
+
+<details>
+<summary>Migration guide</summary>
+
+Before:
+\`\`\`ts
+// old code
+\`\`\`
+
+After:
+\`\`\`ts
+// new code
+\`\`\`
+
+</details>
+```
+
+**Collapsible explanations** - use for supplementary context:
+
+```markdown
+<details>
+<summary>Why SQLite?</summary>
+
+- **Automatic persistence**: Data survives process restarts
+- **Lower memory usage**: No need to keep entire documents in memory
+
+</details>
+```
+
+**Platform support tables:**
+
+```markdown
+<details>
+<summary>Platform support</summary>
+
+| Platform                   | Wrapper                          | Library                           |
+| -------------------------- | -------------------------------- | --------------------------------- |
+| Cloudflare Durable Objects | `DurableObjectSqliteSyncWrapper` | Built-in `ctx.storage`            |
+| Node.js/Deno               | `NodeSqliteWrapper`              | `better-sqlite3` or `node:sqlite` |
+
+</details>
+```
+
+### GitHub release link
+
+Add a link to the GitHub release at the end of each release section:
+
+- **For minor releases**: Place after the last content section and before the `---` separator
+- **For patch releases**: Place after the bulleted list of changes
+
+```markdown
+[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.3.0)
+```
+
+### Patch releases
+
+Add patch releases at the bottom of the minor release file, after a horizontal rule. List in chronological order:
+
+```markdown
+---
+
+## Patch releases
+
+### v4.2.1
+
+- Fix text selection flakiness when clicking into text shapes. ([#3643](https://github.com/tldraw/tldraw/pull/3643))
+
+[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.2.1)
+
+### v4.2.2
+
+- Fix arrow binding when target shape is rotated. ([#3650](https://github.com/tldraw/tldraw/pull/3650))
+
+[View release on GitHub](https://github.com/tldraw/tldraw/releases/tag/v4.2.2)
+```
+
+### Horizontal rules
+
+Use `---` only before the `## Patch releases` section. Do not use horizontal rules elsewhere.
+
+### Headings
+
+Use sentence case: "API changes" not "API Changes", "Bug fixes" not "Bug Fixes".
+
+### Frontmatter
+
+```yaml
+---
+title: 'v4.3.0'
+created_at: 12/19/2024
+updated_at: 12/19/2024
+keywords:
+  - changelog
+  - release
+  - v4.3
+  - v4.3.0
+  - v4.3.1
+  - feature-keyword
+---
+```
+
+- Dates in MM/DD/YYYY format
+- Always include `changelog` and `release` as keywords
+- Include the minor version without patch (e.g., `v4.3`), the `.0` release, and all patch versions
+- Add 2-5 content-relevant keywords (lowercase, hyphens for multi-word)