|
| 1 | +--- |
| 2 | +alwaysApply: true |
| 3 | +--- |
| 4 | + |
| 5 | +## Structure |
| 6 | + |
| 7 | +1. **Summary section** (before `<!--truncate-->`) |
| 8 | + - Lead with most impactful changes |
| 9 | + - Group related items into logical sections |
| 10 | + - List breaking changes with links to migration sections |
| 11 | + - Use bullet lists for quick scanning |
| 12 | + |
| 13 | +2. **`<!--truncate-->`** - Marks preview cutoff |
| 14 | + |
| 15 | +3. **Detailed sections** (after truncate) |
| 16 | + - Expand on summary items with examples |
| 17 | + - Group related changes under shared headers |
| 18 | + - End with Migration Guide for breaking changes |
| 19 | + - Close with "Upgrade support" linking to Discord/GitHub issues |
| 20 | + |
| 21 | +## Imports |
| 22 | + |
| 23 | +Place after frontmatter, before content: |
| 24 | + |
| 25 | +```tsx |
| 26 | +import Link from '@docusaurus/Link'; |
| 27 | +import DiffEditor from '@site/src/components/DiffEditor'; |
| 28 | +import TypeScriptEditor from '@site/src/components/TypeScriptEditor'; |
| 29 | +import PkgTabs from '@site/src/components/PkgTabs'; |
| 30 | +import StackBlitz from '@site/src/components/StackBlitz'; |
| 31 | +``` |
| 32 | + |
| 33 | +## Code Examples |
| 34 | + |
| 35 | +**Before/After changes:** Use `<DiffEditor>` with two code blocks titled "Before" and "After" |
| 36 | + |
| 37 | +**Interactive TypeScript:** Use `<TypeScriptEditor>` for live examples |
| 38 | + |
| 39 | +**Package installation:** Use `<PkgTabs pkgs="@data-client/react@^0.X.0" upgrade />` |
| 40 | + |
| 41 | +**Embedded demos:** Use `<StackBlitz app="app-name" file="path/to/file.tsx" />` |
| 42 | + |
| 43 | +## Conventions |
| 44 | + |
| 45 | +- **Each change must include:** a link to the PR (or commit if no PR) and relevant doc links |
| 46 | +- Link PRs: `[#1234](https://github.com/reactive/data-client/pull/1234)` |
| 47 | +- Link commits: `` [`abc123`](https://github.com/reactive/data-client/commit/abc123) `` |
| 48 | +- Link docs: `[Controller](/docs/api/Controller)` or `[Entity](/rest/api/Entity)` |
| 49 | +- Use `:::note` / `:::tip` / `:::warning` for callouts |
| 50 | +- Use `// highlight-next-line` in code blocks for emphasis |
| 51 | + |
| 52 | +## Migration Guide Section |
| 53 | + |
| 54 | +- Start with package upgrade command via `<PkgTabs>` |
| 55 | +- Each breaking change gets its own `### Heading {#anchor}` |
| 56 | +- Show before/after with `<DiffEditor>` |
| 57 | +- End with upgrade support blurb: |
| 58 | + |
| 59 | +```md |
| 60 | +### Upgrade support |
| 61 | + |
| 62 | +As usual, if you have any troubles or questions, feel free to join our [](https://discord.gg/wXGV27xm6t) or [file a bug](https://github.com/reactive/data-client/issues/new/choose) |
| 63 | +``` |
| 64 | + |
| 65 | +## Naming Convention |
| 66 | + |
| 67 | +Files: `YYYY-MM-DD-vX.Y-short-description.md` |
0 commit comments