From 90f074eae1d59bdc1ac4ec6c22907593af00a3ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Kuna?= <1282324+codecalm@users.noreply.github.com> Date: Wed, 12 Aug 2026 00:38:50 +0200 Subject: [PATCH] Make changeset descriptions short and consistent (#2854) --- .agents/rules/main.mdc | 3 +- .agents/skills/generate-changeset/SKILL.md | 84 ++++++++++++++++--- .changeset/a11y-buttons-not-links.md | 2 +- .changeset/a11y-component-aria-roles.md | 2 +- .changeset/a11y-core-focus-motion-contrast.md | 2 +- .changeset/a11y-datepicker-dropzone.md | 2 +- .changeset/a11y-fieldset-legend-groups.md | 2 +- .changeset/a11y-form-labels-validation.md | 2 +- .changeset/a11y-skip-link-landmarks.md | 2 +- .changeset/a11y-status-and-chart-labels.md | 2 +- .changeset/a11y-wcag-fixes.md | 2 +- .changeset/add-text-gray-utilities.md | 2 +- .changeset/astro-migration.md | 2 +- .changeset/badge-tag-list-rename.md | 10 +-- .changeset/bootstrap-exports-cleanup.md | 2 +- .changeset/bootstrap-vendor-migration.md | 2 +- .changeset/card-gradient-components.md | 1 - .changeset/card-header-footer-bg-vars.md | 2 +- .changeset/change-password-modal.md | 3 +- .changeset/clean-up-hardcoded-rem-values.md | 2 +- .changeset/confirm-delete-modal.md | 3 +- .changeset/crypto-dashboard.md | 1 - .changeset/crypto-data-files.md | 3 +- .changeset/docs-css-variables-font-sizes.md | 2 +- .changeset/docs-how-to-contribute-sync.md | 2 +- .changeset/docs-singular-component-names.md | 2 +- .changeset/edit-profile-modal.md | 1 - .changeset/extract-liquid-filters-to-lib.md | 2 +- .../fix-border-color-translucent-dark.md | 2 +- .changeset/fix-card-header-cap-bg.md | 2 +- .changeset/fix-card-tabs-dropdown-zindex.md | 2 +- .changeset/fix-checkbox-dark-border.md | 2 +- .../fix-dark-mode-selection-contrast.md | 2 +- .changeset/fix-disabled-input-dark-theme.md | 2 +- .changeset/fix-form-select-icon-padding.md | 2 +- .../fix-form-select-input-group-shadow.md | 2 +- .changeset/fix-gradient-utilities-docs.md | 2 +- .changeset/fix-gray-fg-token-mapping.md | 2 +- .changeset/fix-icon-transform-animations.md | 2 +- .../fix-input-button-size-consistency.md | 2 +- .changeset/fix-payment-icons-dark-mode.md | 2 +- .changeset/fix-ribbon-example-background.md | 2 +- .changeset/fix-status-colors-variables.md | 2 +- .changeset/fix-steps-typography-collision.md | 2 +- .../fix-tom-select-missing-variables.md | 2 +- .changeset/fix-white-space-scrollbar.md | 2 +- .changeset/flags-avatars-updates.md | 3 +- .changeset/format-lint-tooling-sync.md | 2 +- .changeset/fresh-rockets-retire.md | 2 +- .changeset/funny-kings-double.md | 2 +- .changeset/geist-fonts.md | 3 +- .changeset/grumpy-foxes-shake.md | 2 +- .changeset/import-icons-scripts.md | 2 +- .changeset/light-dark-root-color-tokens.md | 2 +- .changeset/many-dogs-rest.md | 3 +- .changeset/menu-structure-refactor.md | 3 +- .changeset/migrate-css-logical-properties.md | 4 +- .changeset/migrate-rgba-to-color-mix.md | 3 +- .changeset/migrate-rollup-to-vite.md | 2 +- .changeset/modern-dots-bathe.md | 2 +- .changeset/navbar-side-refactor.md | 2 +- .changeset/new-task-modal.md | 1 - .changeset/postcss-custom-property-prefix.md | 2 +- .changeset/pretty-chefs-design.md | 2 +- .changeset/progress-variants-docs.md | 2 +- .changeset/redundant-nullish-operator.md | 1 - .changeset/remove-unused-scss-variables.md | 4 +- .changeset/restore-caret-width.md | 2 +- .changeset/scss-module-migration.md | 2 +- .changeset/scss-unit-tests.md | 2 +- .changeset/silly-crabs-walk.md | 1 - .changeset/slim-down-dist-libs.md | 2 +- .changeset/stylelint-scss-cleanup.md | 2 +- .changeset/tasks-list-page.md | 3 +- .changeset/theme-settings-auto-mode.md | 2 +- .changeset/tricky-moons-laugh.md | 2 +- .changeset/update-icons-3.36.1.md | 1 - .changeset/update-illustrations-1.16.0.md | 2 +- .changeset/update-shadow-tokens.md | 2 +- .changeset/upgrade-apexcharts.md | 3 +- .changeset/young-needles-love.md | 2 +- 81 files changed, 150 insertions(+), 110 deletions(-) diff --git a/.agents/rules/main.mdc b/.agents/rules/main.mdc index dabee63db..0af24066a 100644 --- a/.agents/rules/main.mdc +++ b/.agents/rules/main.mdc @@ -84,8 +84,9 @@ Shared instructions for all AI agents (Claude Code, Cursor, etc.). Canonical age ### Changesets +- **Always use the `generate-changeset` skill** (`.agents/skills/generate-changeset/SKILL.md`) to write a changeset — both when asked for one and on your own before committing or opening a PR that touches `core/`, `preview/`, or `docs/`. Do not hand-write the file. - Each change gets a separate file in `.changeset/` with a descriptive kebab-case filename (e.g. `progress-sizes.md`). -- One sentence per changeset, starting with an action verb (`Added`, `Updated`, `Fixed`, `Removed`), with backticks for code elements (`.btn-ghost`, `stroke-width`, `1.5`, `arrow-up`). +- One sentence per changeset, **130 characters or fewer** (hard ceiling 160, only when a longer list is the actual content), starting with an action verb (`Added`, `Updated`, `Fixed`, `Removed`), with backticks for code elements (`.btn-ghost`, `stroke-width`, `1.5`, `arrow-up`). A changeset is one changelog line — keep the reasons, implementation notes, and affected-file lists in the PR description. Always name a concrete component, class, variable, page, or dependency; "Fixed mixed declarations in SCSS" tells a reader nothing. - Version bumps: **major** = breaking changes; **minor** = new features, components, or pages; **patch** = bug fixes, small improvements, style/accessibility tweaks. - Packages: `"@tabler/core"` for SCSS/JS/classes, `"@tabler/preview"` for demo pages, `"@tabler/docs"` for documentation; list multiple packages when the change spans areas. - Example: diff --git a/.agents/skills/generate-changeset/SKILL.md b/.agents/skills/generate-changeset/SKILL.md index 29483deef..d5420964b 100644 --- a/.agents/skills/generate-changeset/SKILL.md +++ b/.agents/skills/generate-changeset/SKILL.md @@ -2,8 +2,10 @@ name: generate-changeset description: >- Creates a Tabler changeset file in `.changeset/` from the current code - changes. Use when the user asks for a changeset, version bump, release note - entry, or changelog entry for @tabler/core, @tabler/preview, or @tabler/docs. + changes. Use this skill for every changeset in this repo — when the user asks + for a changeset, version bump, release note, or changelog entry, and also on + your own whenever a change under `core/`, `preview/`, or `docs/` is about to + be committed or opened as a PR. Never hand-write the file instead. --- # Generate changeset @@ -45,8 +47,13 @@ When unsure between patch and minor: prefer **patch** for fixes and visual tweak ## 4. Write the description -- **Exactly one sentence** +A changeset is one line in a changelog. It is not a summary of the work. + +- **One sentence, 130 characters or fewer**, including backticks. This is the limit to write to. +- **160 characters is a hard ceiling.** Go over 130 only when a shorter version would drop a fact the reader needs — a long list of affected components, for example. Never go over 160. - Start with: `Added`, `Updated`, `Fixed`, or `Removed` +- Say **what** changed and **where** (component, page, utility). Then stop. +- **Name at least one concrete thing**: a component, class, CSS variable, Sass variable, page, data file, or dependency. "Fixed mixed declarations in SCSS" and "Updated flags and avatars styling" name nothing — a reader cannot tell whether the change affects them. There is no minimum length, but an entry under ~40 characters that names nothing is almost always too vague; a dependency bump like `Updated Bootstrap to v5.3.8.` is fine at 28, because the dependency and version are the content. - Use **backticks** for code tokens: - Classes: `.btn-ghost`, `.progress-lg` - Properties: `stroke-width`, `border-radius` @@ -54,15 +61,64 @@ When unsure between patch and minor: prefer **patch** for fixes and visual tweak - Icons: `arrow-up` - Attributes: `aria-label`, `data-*` - Functions: `addEventListener()` -- Be specific about **what** changed and **where** (component, page, mixin) -**Patterns from this repo:** +**Count the characters before writing the file:** -- Component: `Added Progress Steps component for step-by-step navigation indicators.` -- Size variant: `Added \`.progress-lg\` and \`.progress-xl\` size variants for the progress component.` -- Bug fix: `Fixed dark mode text selection contrast by adding \`--tblr-selection-bg\` CSS variable with \`0.4\` opacity override in dark mode.` -- New page: `Added new onboarding page with progress indicator and navigation layout.` -- Cross-package: `Added background pattern utilities and documentation, including updated preview demos.` +```shell +printf '%s' 'Added Progress Steps component for step-by-step navigation indicators.' | wc -c +``` + +If it is over the limit, **cut words**. Never split it into two sentences, a second paragraph, or a bullet list. + +### Leave this out + +These belong in the PR description or the commit body, not in the changeset: + +- Why the change was made, or what was broken before +- How it was built: file paths, mixin internals, refactor steps +- A list of every affected component, page, or variable +- Migration and rollout notes, unless the change is breaking + +**Cut the tail first.** An over-long entry in this repo is almost always a good sentence with a trailing justification clause glued on. Delete that clause and the length problem is usually solved: + +```text +… and removed duplicate exports from `tabler.js` for better maintainability. +… with `var(--tblr-bg-surface-secondary)` so it adapts to dark mode. +… live in one `:root` declaration instead of separate dark-mode overrides. +``` + +### Examples + +Good — short and specific: + +```text +(70) Added Progress Steps component for step-by-step navigation indicators. +(81) Added `.progress-lg` and `.progress-xl` size variants for the progress component. +(78) Fixed dark mode text selection contrast with a `--tblr-selection-bg` variable. +(58) Removed `license_key` option from the HugeRTE init object. +``` + +Too vague — name the thing that changed: + +```text + (33) ❌ Fixed mixed declarations in SCSS. + (79) ✅ Fixed Sass mixed-declaration warnings in the navbar, card, nav and table styles. + (26) ❌ Updated activity messages. + (82) ✅ Updated the activity feed messages in `activity.json` and the activity preview page. +``` + +Too long — trim it: + +```text +(175) ❌ Fixed accessibility issues for skip links, keyboard focus, `prefers-reduced-motion`, form labels, and action controls that incorrectly used links instead of `button` elements. +(117) ✅ Fixed accessibility issues in skip links, keyboard focus, `prefers-reduced-motion`, form labels, and action controls. +``` + +Over 130 but justified — the list of components is the content, and cutting it would say nothing: + +```text +(137) Added missing ARIA roles and states to `Pagination`, `NavSegmented`, `Accordion`, `Steps`, tabs, `Modal`, `Offcanvas` and `CarouselCard`. +``` Write in **simple English**, even if the user asked in another language. @@ -96,12 +152,15 @@ Rules: - Frontmatter uses quoted package names: `"@tabler/core": patch` - Blank line after closing `---` - No title heading, no bullet list in the body +- Body is a single line — no second paragraph - Bump values: `patch`, `minor`, or `major` only ## 7. Validate before writing - [ ] Every listed package has touched paths in the diff - [ ] Description is one sentence with action verb, in simple English +- [ ] Description is **130 characters or fewer** — counted, not estimated; over 130 only with a reason, never over 160 +- [ ] Description names a concrete component, class, variable, page, file, or dependency - [ ] Code tokens use backticks - [ ] Filename is kebab-case and not already used for a different change - [ ] SCSS/CSS/JS behavior changes include `@tabler/core` when under `core/` @@ -111,7 +170,8 @@ Rules: After creating the file: 1. Show the full changeset content in a fenced `markdown` block (for easy copy/review) -2. Briefly explain **why** each package and bump level was chosen -3. If no changeset is needed (docs-only CI, lockfile-only, etc.), say so and why +2. Give the description length, e.g. `112 / 130 characters`; if it is over 130, say why the extra words earn their place +3. Briefly explain **why** each package and bump level was chosen +4. If no changeset is needed (docs-only CI, lockfile-only, etc.), say so and why Do **not** run `changeset version` or `changeset publish` unless the user explicitly asks. \ No newline at end of file diff --git a/.changeset/a11y-buttons-not-links.md b/.changeset/a11y-buttons-not-links.md index edc0f1c6c..bb7953e55 100644 --- a/.changeset/a11y-buttons-not-links.md +++ b/.changeset/a11y-buttons-not-links.md @@ -2,4 +2,4 @@ "@tabler/preview": patch --- -Converted `` controls that only trigger JavaScript (dropdown toggles, toast dismiss, modal and carousel controls) into real `