--- name: release-notes description: >- Write or update the intro of a Tabler GitHub release — `.github/release-notes/.md`, the part above the generated Core, Demo and Docs lists. Use whenever the user asks for release notes, a release description, a release intro or "what's new in X.Y", and proactively before a minor release when the version PR is open and the intro file is missing. Covers where the facts come from, the fixed layout (cover, headline features with a picture each, then the other changes), the image rules, the tone and how to check the result. --- # Release notes intro The GitHub release body has two parts. The intro is hand-written in `.github/release-notes/.md` (for example `1.6.0.md`). The `## Core changes`, `## Demo changes` and `## Docs changes` lists under it are generated by `pnpm run release-notes` from the `CHANGELOG.md` files. Never write those lists by hand, and don't repeat them in the intro. `.github/release-notes/README.md` explains the pipeline. Read it first. A minor release always gets an intro. A patch release gets one only when it has something a user should hear about. Otherwise the generated lists are enough. The workflow reads the intro from the commit it publishes, so the file must be on `dev` **before** the `chore: update versions` PR is merged. After the release, the body is never rewritten. A later fix has to be made by editing the release on GitHub. ## 1. Collect the facts Never write the intro from memory. 1. Read every file in `.changeset/*.md`. The `minor` entries for `@tabler/core` are the candidates for headline features. The `patch` entries feed the smaller sections. 2. Check the milestone on GitHub (`gh api repos/tabler/tabler/milestones`) for closed PRs that have no changeset. 3. For each headline feature, read its docs page (`summary`, `description` and the `##` headings in `docs/content/ui/**`). The intro should describe the feature the way the docs do, with the same class names, attributes and events. 4. Read the upgrade guide for this version (`docs/content/ui/getting-started/upgrade/.mdx`). The `## Upgrading` section in the intro summarizes it and links to it. 5. Before you print a class, an attribute, an event or a number (like the kB saved), check it against the current source. ## 2. Layout The layout is fixed, so readers can compare releases. Copy the newest intro (`1.6.0.md`) and keep this order: ````text cover (light + dark) One paragraph: "Tabler X.Y is out." + the three to five biggest things + a rough count of the rest. ## ← one section per headline feature screenshot ← the picture comes right after the heading, before the text Two or three sentences on what it gives the user. ## … --- ← separator between the headline features and the rest ## ← grouped smaller changes, no pictures, one short paragraph each ## Demo and docs ## Upgrading ← always last: what can break, what is deprecated, link to the guide ```` Rules: - **Every headline feature has its own `##` section.** Don't group eight components under one "New components" heading with bold leads. Each one gets a heading, a picture and its own text. - **A headline feature needs a picture.** If there is none, the feature belongs below the separator, or you make the picture first (section 3). - **2 to 4 sentences per feature.** Say what it is, when you'd use it, and the one API detail people will look for (a class, a `data-bs-*` attribute, an event). Mention what it replaces or deprecates, for example "Litepicker is deprecated". - **Order the headlines by weight.** Put the one people waited for first, and small helpers last. - **Below the separator, group by theme** (colors, layout, performance, JS behaviour), not by package. Use one paragraph per group and no bullet dumps. The generated lists already have every item. - **`## Upgrading` closes the intro.** Say whether markup has to change, list what can break a build, list what is deprecated with its replacement, and link to `https://docs.tabler.io/ui/getting-started/upgrade/`. It has to agree with the guide. ## 3. Images All images live next to the intro and are named `-.png` / `--dark.png`. - **Cover:** `-cover.png` and `-cover-dark.png`, 1200×630. Check the size with `sips -g pixelWidth -g pixelHeight `. The cover shows the release date, so re-export it if the release slips. - **Feature pictures:** make them with the `screenshots/` app (see the `screenshots` skill). Copy the 1x `.png` and `-dark.png` from `screenshots/captures/` and rename them with the version prefix. - Use a `` block for every image, so GitHub shows the dark one in dark mode: ```html Legend ``` - Link to the raw file on the `dev` **branch**, never on a tag. A tag like `@tabler/core@1.6.0` has a slash, and `raw.githubusercontent.com` reads it as part of the path. - The `alt` is the feature name, the same as the heading. - The images must be pushed to `dev` before the release, or the published body shows broken images. ## 4. Tone - Simple English, short sentences, contractions allowed. Write the way the `write-docs` skill asks. - No marketing words: no "powerful", "seamless", "blazing", "game-changer" and no exclamation marks. Say what changed and what it does. - Write to the user: "you can", "the sidebar folds now", not "we are excited to announce". - Wrap code names in backticks: classes, attributes, events, variables and file paths. - Give numbers when they're real: "about 110 kB came off `tabler.min.css`", "seven chart types". - Run the `humanize-text` skill over the draft if it reads stiff. ## 5. Check the result - `git diff --check` and a read-through in a Markdown preview in both color modes. - Every image URL resolves once pushed: `git cat-file -e origin/dev:.github/release-notes/` for each one. - Every headline feature has a changeset, and every `minor` core changeset that adds a component or a page is mentioned somewhere in the intro. - On `dev`, `pnpm run release-notes` builds the body from the working tree's version, so it prints the previous release without the new intro. To see the real body, run it on the bot's files. The steps are in `.agents/agents/release-check.md`, section 5. - The `release-check` agent audits the intro as part of the pre-release checklist. Run it before the version PR is merged. ## 6. Checklist - [ ] Facts come from the changesets, the milestone, the docs pages and the upgrade guide - [ ] Cover in light and dark, 1200×630, with the right date - [ ] One `##` section per headline feature: heading, ``, 2–4 sentences - [ ] `---` separator, then the smaller changes grouped by theme - [ ] `## Upgrading` last, in line with the upgrade guide, linking to it - [ ] Image URLs point to `dev`, files named `-[-dark].png` - [ ] On `dev` before the version PR is merged