From 2f3e20df4deaad7c57f9990d8fc47f37d670fc38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robson=20J=C3=BAnior?= Date: Sun, 26 Jul 2026 19:13:03 -0300 Subject: [PATCH 1/3] [NO-ISSUE] fix(webkit): replace deep-relative theme imports with @aziontech/theme/animations --- .../actions/segmented-button/presets/transitions.ts | 5 +---- .../src/components/data/code-block/presets/transitions.ts | 5 +---- .../navigation-menu/composables/navigation-menu-css-vars.js | 5 +---- .../components/navigation/tab-view/presets/transitions.ts | 5 +---- .../src/components/overlay/dialog/presets/transitions.ts | 6 ++---- .../src/components/overlay/drawer/presets/transitions.ts | 6 ++---- .../overlay/tooltip/presets/popup-scale-transition.js | 5 +---- 7 files changed, 9 insertions(+), 28 deletions(-) diff --git a/packages/webkit/src/components/actions/segmented-button/presets/transitions.ts b/packages/webkit/src/components/actions/segmented-button/presets/transitions.ts index 9722472d6..1b15e888f 100644 --- a/packages/webkit/src/components/actions/segmented-button/presets/transitions.ts +++ b/packages/webkit/src/components/actions/segmented-button/presets/transitions.ts @@ -1,7 +1,4 @@ -import { - curve, - duration -} from '../../../../../../theme/src/tokens/primitives/animations/animate.js' +import { curve, duration } from '@aziontech/theme/animations' /** Selection highlight pill — values read only from `animate.js`. */ export const segmentedButtonIndicatorMotion = { diff --git a/packages/webkit/src/components/data/code-block/presets/transitions.ts b/packages/webkit/src/components/data/code-block/presets/transitions.ts index 26a1d6b61..3757d60ba 100644 --- a/packages/webkit/src/components/data/code-block/presets/transitions.ts +++ b/packages/webkit/src/components/data/code-block/presets/transitions.ts @@ -1,7 +1,4 @@ -import { - curve, - duration -} from '../../../../../../theme/src/tokens/primitives/animations/animate.js' +import { curve, duration } from '@aziontech/theme/animations' /** Tab underline indicator — values read only from `animate.js`. */ export const codeBlockIndicatorMotion = { diff --git a/packages/webkit/src/components/navigation/navigation-menu/composables/navigation-menu-css-vars.js b/packages/webkit/src/components/navigation/navigation-menu/composables/navigation-menu-css-vars.js index d0a5a335a..f84ac83ea 100644 --- a/packages/webkit/src/components/navigation/navigation-menu/composables/navigation-menu-css-vars.js +++ b/packages/webkit/src/components/navigation/navigation-menu/composables/navigation-menu-css-vars.js @@ -1,7 +1,4 @@ -import { - curve, - duration -} from '../../../../../../theme/src/tokens/primitives/animations/animate.js' +import { curve, duration } from '@aziontech/theme/animations' export const POPUP_WIDTH = '--popup-width' export const POPUP_HEIGHT = '--popup-height' diff --git a/packages/webkit/src/components/navigation/tab-view/presets/transitions.ts b/packages/webkit/src/components/navigation/tab-view/presets/transitions.ts index 948124bf4..79a69c9dd 100644 --- a/packages/webkit/src/components/navigation/tab-view/presets/transitions.ts +++ b/packages/webkit/src/components/navigation/tab-view/presets/transitions.ts @@ -1,7 +1,4 @@ -import { - curve, - duration -} from '../../../../../../theme/src/tokens/primitives/animations/animate.js' +import { curve, duration } from '@aziontech/theme/animations' export type TabViewSlideDirection = 'left' | 'right' | null diff --git a/packages/webkit/src/components/overlay/dialog/presets/transitions.ts b/packages/webkit/src/components/overlay/dialog/presets/transitions.ts index 82fca6573..3ec3d8607 100644 --- a/packages/webkit/src/components/overlay/dialog/presets/transitions.ts +++ b/packages/webkit/src/components/overlay/dialog/presets/transitions.ts @@ -1,7 +1,5 @@ -import { - curve, - duration -} from '../../../../../../theme/src/tokens/primitives/animations/animate.js' +import { curve, duration } from '@aziontech/theme/animations' + import { DRAWER_EXIT_MS, getDrawerTransitionStyle } from '../../drawer/presets/transitions' import { bottomSheetPanelMotionClasses, diff --git a/packages/webkit/src/components/overlay/drawer/presets/transitions.ts b/packages/webkit/src/components/overlay/drawer/presets/transitions.ts index 3085fc90d..0ce7acd6f 100644 --- a/packages/webkit/src/components/overlay/drawer/presets/transitions.ts +++ b/packages/webkit/src/components/overlay/drawer/presets/transitions.ts @@ -1,7 +1,5 @@ -import { - curve, - duration -} from '../../../../../../theme/src/tokens/primitives/animations/animate.js' +import { curve, duration } from '@aziontech/theme/animations' + import { bottomSheetPanelMotionClasses, bottomSheetPanelStateClasses diff --git a/packages/webkit/src/components/overlay/tooltip/presets/popup-scale-transition.js b/packages/webkit/src/components/overlay/tooltip/presets/popup-scale-transition.js index f30caf9d2..278f3899b 100644 --- a/packages/webkit/src/components/overlay/tooltip/presets/popup-scale-transition.js +++ b/packages/webkit/src/components/overlay/tooltip/presets/popup-scale-transition.js @@ -1,7 +1,4 @@ -import { - curve, - duration -} from '../../../../../../theme/src/tokens/primitives/animations/animate.js' +import { curve, duration } from '@aziontech/theme/animations' /** * Tooltip popup motion — timing from `animate.js` (`popup-scale-in` / `popup-scale-out`). From 622bbb818effdfa457ac1d5b6eb5eab561cc1d0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robson=20J=C3=BAnior?= Date: Sun, 26 Jul 2026 19:13:18 -0300 Subject: [PATCH 2/3] [NO-ISSUE] fix: move vue-tsc to devDependencies (webkit and theme) --- packages/theme/package.json | 2 +- packages/webkit/package.json | 4 ++-- pnpm-lock.yaml | 8 ++++---- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/theme/package.json b/packages/theme/package.json index caaaa37c9..8db24655b 100644 --- a/packages/theme/package.json +++ b/packages/theme/package.json @@ -31,7 +31,7 @@ "ui-kit", "token-generator" ], - "dependencies": { + "devDependencies": { "vue-tsc": "^3.2.5" }, "files": [ diff --git a/packages/webkit/package.json b/packages/webkit/package.json index 6663b2b0e..070afcc44 100644 --- a/packages/webkit/package.json +++ b/packages/webkit/package.json @@ -53,7 +53,6 @@ "clsx": "^2.1.1", "tailwind-merge": "^3.6.0", "vee-validate": "^4.15.1", - "vue-tsc": "^3.2.5", "zod": "^3.23.0" }, "peerDependencies": { @@ -89,7 +88,8 @@ "stylelint": "^17.7.0", "vitest": "^4.1.9", "vue": "^3.5.29", - "vue-eslint-parser": ">=9" + "vue-eslint-parser": ">=9", + "vue-tsc": "^3.2.5" }, "files": [ "src", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index da8c75e2b..e57a1f363 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -263,7 +263,7 @@ importers: version: 4.1.0 packages/theme: - dependencies: + devDependencies: vue-tsc: specifier: ^3.2.5 version: 3.3.7(typescript@6.0.3) @@ -291,9 +291,6 @@ importers: vee-validate: specifier: ^4.15.1 version: 4.15.1(vue@3.5.40(typescript@6.0.3)) - vue-tsc: - specifier: ^3.2.5 - version: 3.3.7(typescript@6.0.3) zod: specifier: ^3.23.0 version: 3.25.76 @@ -346,6 +343,9 @@ importers: vue-eslint-parser: specifier: '>=9' version: 10.4.1(eslint@9.39.5(jiti@2.6.1)) + vue-tsc: + specifier: ^3.2.5 + version: 3.3.7(typescript@6.0.3) packages: From b6ec6c5d11568b90119b9f98055c9fd3d6318767 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robson=20J=C3=BAnior?= Date: Sun, 26 Jul 2026 19:31:05 -0300 Subject: [PATCH 3/3] [NO-ISSUE] docs: reconcile release types with release-please; drop unused hotfix type --- .claude/commands/create-branch.md | 2 +- .claude/commands/open-pr.md | 10 +++--- .claude/rules/deprecation.md | 2 +- .claude/rules/git-workflow.md | 2 +- .claude/rules/release-types.md | 57 +++++++++++++++--------------- CONTRIBUTING.md | 29 +++++++-------- commitlint.config.js | 17 ++++----- packages/webkit/docs/DOC_LINTS.md | 16 ++++----- packages/webkit/docs/PROCESS.md | 31 ++++++++-------- packages/webkit/docs/STYLEGUIDE.md | 11 +++--- 10 files changed, 92 insertions(+), 85 deletions(-) diff --git a/.claude/commands/create-branch.md b/.claude/commands/create-branch.md index 32b1385a1..0a6774e04 100644 --- a/.claude/commands/create-branch.md +++ b/.claude/commands/create-branch.md @@ -15,7 +15,7 @@ You are running `/create-branch`. Cut a fresh branch off the latest `main`, name 1. **Sync.** Run `git fetch origin --prune`. 2. **Read the change (if any).** If the working tree already has changes, run `git status` and `git diff` and use them to infer the branch `type` and a slug. If the tree is clean, derive both from `$ARGUMENTS` (ask for a 2–4 word description if none was given). -3. **Type.** Pick from the same enum the repo's commit convention uses: `feat` (default — new component/prop/event/export), `fix`, `hotfix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `ci`, `revert`. +3. **Type.** Pick from the same enum the repo's commit convention uses: `feat` (default — new component/prop/event/export), `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `ci`, `revert`. Only `feat` / `fix` (or a breaking `!`) actually release (see [`release-types.md`](../rules/release-types.md)). 4. **Related issue (optional).** Ask: "Which issue does this relate to? (`ENG-1234`, or leave blank for `NO-ISSUE`)". A blank answer is fine — treat it as no issue. Do not block on it. 5. **Create.** - With an issue: `git checkout -b /- origin/main` diff --git a/.claude/commands/open-pr.md b/.claude/commands/open-pr.md index 443e3a8b2..9bb306b43 100644 --- a/.claude/commands/open-pr.md +++ b/.claude/commands/open-pr.md @@ -1,5 +1,5 @@ --- -description: Open a PR to `main`. Analyzes the diff to pick the Conventional Commit type/scope (drives the semantic-release bump), prompts for the related issue (optional), commits by context, pushes, and opens the PR. +description: Open a PR to `main`. Analyzes the diff to pick the Conventional Commit type/scope (drives the release-please bump), prompts for the related issue (optional), commits by context, pushes, and opens the PR. argument-hint: [PR title or focus] --- @@ -9,8 +9,8 @@ You are running `/open-pr`. Land the current working changes as a pull request a ## Source of truth -- Commit format and type→bump: [`CONTRIBUTING.md`](../../CONTRIBUTING.md) § Commit convention and [`commitlint.config.js`](../../commitlint.config.js). -- Release rules: `packages//.releaserc` (semantic-release; merges to `main` cut the version). +- Commit format and type→release mapping: [`CONTRIBUTING.md`](../../CONTRIBUTING.md) § Commit convention, [`commitlint.config.js`](../../commitlint.config.js), and [`release-types.md`](../rules/release-types.md). +- Release automation: [`release-please-config.json`](../../release-please-config.json) — merges to `main` update the pending Release PR; merging the Release PR cuts the version. Stock release-please: only `feat` / `fix` / breaking release. ## Steps @@ -19,7 +19,7 @@ You are running `/open-pr`. Land the current working changes as a pull request a ### 1. Analyze the diff (drives the version bump) Run `git diff` (staged + unstaged) and determine, from the change itself: -- **type** → `feat` (new component / prop / event / slot / public export), `fix` / `hotfix` (bug, a11y, visual regression), `refactor`, `perf`, `docs`, `style`, `chore`, `test`, `ci`, `revert`. This sets the bump: `feat`→minor; `fix`/`hotfix`/`chore`/`docs`/`style`/`refactor`/`perf`→patch; `test`/`ci`/`revert`→no release. +- **type** → `feat` (new component / prop / event / slot / public export), `fix` (bug, a11y, visual regression — anything that must ship), `refactor`, `perf`, `docs`, `style`, `chore`, `test`, `ci`, `revert`. Release effect (release-please): `feat`→minor; `fix`→patch; breaking→major; **every other type → no release on its own** (urgent production fixes are `fix` — there is no `hotfix` type). - **scope** → the package without its namespace (`webkit`, `theme`, `icons`), inferred from the changed paths. - **breaking?** → a removed or renamed public prop, event, slot, or export ⇒ major. Mark it with `!` and a `BREAKING CHANGE:` footer. **Confirm with the user before marking a change breaking.** @@ -45,7 +45,7 @@ If the diff spans multiple packages, prefer **one commit per scope** (CONTRIBUTI ### 6. Push and open the PR - `git push -u origin `. - If a PR already exists for the branch, update it; otherwise `gh pr create --base main --head `. -- **Title:** the conventional commit header (or `$ARGUMENTS`). **Body:** `## Summary` (what + why) and `## Notes`; call out any new dependency and any breaking change; reference the issue. No Figma links, no attribution footer. +- **Title:** the conventional commit header (or `$ARGUMENTS`). Merges are **squash merges**, so the PR title is the commit release-please parses — keep it commitlint-valid, and put `!` in the title for a breaking change. **Body:** `## Summary` (what + why) and `## Notes`; call out any new dependency and any breaking change; reference the issue. No Figma links, no attribution footer. - Report the PR URL. ## Rules diff --git a/.claude/rules/deprecation.md b/.claude/rules/deprecation.md index be9743d4e..01ab82aff 100644 --- a/.claude/rules/deprecation.md +++ b/.claude/rules/deprecation.md @@ -41,7 +41,7 @@ For a whole component: ## Enforcement - **`webkit/no-deprecated-component`** (ESLint, `error` in `recommended`) flags a consumer importing a component marked deprecated in the catalog. -- **`.releaserc`** (`releaseRules`) maps the bump; a `BREAKING CHANGE:` footer / `!` produces the `major` (see [`release-types.md`](./release-types.md)). +- **release-please** maps the bump; a `BREAKING CHANGE:` footer / `!` produces the `major` (see [`release-types.md`](./release-types.md)). - **`catalog.json`** records `deprecated` per part; `build-catalog.mjs` stamps it and the MCP surfaces it. ## Why this rule exists diff --git a/.claude/rules/git-workflow.md b/.claude/rules/git-workflow.md index ce56582dc..a65cc738b 100644 --- a/.claude/rules/git-workflow.md +++ b/.claude/rules/git-workflow.md @@ -12,7 +12,7 @@ These commands are the **source of truth** for the process. This rule exists onl ## Conventions (already embedded in the flows — repeated here because they are non-negotiable) - **Always base on `main`.** The branch comes off `origin/main`, the PR targets `main`. -- **Branch name:** kebab-case `/-` (or `/` without an issue). `type` comes from the same Conventional Commits enum ([`CONTRIBUTING.md`](../../CONTRIBUTING.md) § Commit convention / [`commitlint.config.js`](../../commitlint.config.js)). That enum must match every `packages/*/.releaserc` — see [`release-types.md`](./release-types.md). +- **Branch name:** kebab-case `/-` (or `/` without an issue). `type` comes from the same Conventional Commits enum ([`CONTRIBUTING.md`](../../CONTRIBUTING.md) § Commit convention / [`commitlint.config.js`](../../commitlint.config.js)). That enum must match the release-please mapping (only `feat`/`fix`/breaking release) — see [`release-types.md`](./release-types.md). - **Commit:** Conventional Commits, commitlint-valid header. **Never** add `Co-Authored-By` or an attribution footer ("Generated with Claude"). **Never** `--no-verify` to skip commitlint. - **Commit/push only as part of `/open-pr`** — running the command is the authorization. Do not commit unrelated changes. - **Shared docs/rules in a separate PR from code.** If the diff mixes code with `.claude/rules/*`, `.claude/skills/*`, `.specs/_template.md`, etc., split them into another PR. A component's own `.specs/.md` stays with the component. diff --git a/.claude/rules/release-types.md b/.claude/rules/release-types.md index 3a7fbee92..9507c529c 100644 --- a/.claude/rules/release-types.md +++ b/.claude/rules/release-types.md @@ -1,52 +1,53 @@ -# Rule: release types — one single set of types across commitlint, `.releaserc`, CONTRIBUTING and commands +# Rule: release types — one single set of types across commitlint, release-please, CONTRIBUTING and commands -The set of Conventional Commit `type`s and the **version bump** of each one are versioned in four places. They **must be identical**. When they diverge, commitlint accepts a commit that `semantic-release` silently ignores (or vice versa), and the `/open-pr` / `/create-branch` flows start offering a type that does not produce the expected release. This rule is what the reviewer enforces in a PR: _"should match release and commit lint"_. +The set of Conventional Commit `type`s and the **release effect** of each one are versioned in four places. They **must be identical**. When they diverge, commitlint accepts a commit that the release automation silently ignores (or the docs promise a bump that never happens), and the `/open-pr` / `/create-branch` flows start offering a type that does not produce the expected release. This rule was originally written for `semantic-release` (`.releaserc` `releaseRules`); **#798 replaced semantic-release with release-please**, whose bump semantics are **not configurable per type** — so the four surfaces now align on release-please's stock behavior instead of a custom table. ## The rule (invariant) -The list of accepted types and the type→bump must be **identical** at these four points: +The list of accepted types and the type→release-effect must be **identical** at these four points: | File | What it defines | |---|---| | [`commitlint.config.js`](../../commitlint.config.js) (`type-enum`) | which types pass `commit-msg` | -| `packages/*/.releaserc` (`releaseRules`) | the bump of each type — in **all** packages: [`webkit`](../../packages/webkit/.releaserc), [`theme`](../../packages/theme/.releaserc), [`icons`](../../packages/icons/.releaserc) | -| [`CONTRIBUTING.md`](../../CONTRIBUTING.md) § Commit convention | the type → bump table, documented for humans | +| [`release-please-config.json`](../../release-please-config.json) (stock `release-type: node`, **no** bump customization) | which types actually release, per release-please semantics | +| [`CONTRIBUTING.md`](../../CONTRIBUTING.md) § Commit convention | the type → release-effect table, documented for humans | | [`open-pr.md`](../commands/open-pr.md) + [`create-branch.md`](../commands/create-branch.md) | the list of types the flows infer/offer | -## Canonical set (today) +## Canonical set (today — release-please semantics) - `feat` → **minor** -- `fix` / `hotfix` / `chore` / `docs` / `style` / `refactor` / `perf` → **patch** -- `test` / `ci` / `revert` → `release: false` (no bump; allowed for hygiene) -- `!` after the type or a `BREAKING CHANGE:` footer → **major** +- `fix` → **patch** +- `!` after the type or a `BREAKING CHANGE:` footer → **major** (on any type) +- `chore` / `docs` / `style` / `refactor` / `perf` / `test` / `ci` / `revert` → **no release on their own**. They are accepted for hygiene and ride along in the next release cut by a `feat`/`fix`; release-please does not count them as releasable units. -Each type is listed **explicitly** in the `releaseRules` of every `.releaserc` — do not rely on the implicit default of the `conventionalcommits` preset. A type without an explicit rule is a divergence waiting to happen. +> **`hotfix` was removed from the enum (2026-07-26).** Its name implied a release, but release-please does not recognize the type — a silent trap for exactly the most urgent commits. It had zero uses in the repo's history, so it was dropped: commitlint now rejects it loudly, and urgent production fixes are committed as `fix`. -## When adding, removing, or re-mapping a type - -Make the four edits **in the same PR**: +## release-please details that matter -1. `commitlint.config.js` → `type-enum`. -2. **Every** `packages/*/.releaserc` → `releaseRules` (webkit, theme, icons). Don't forget any package. -3. `CONTRIBUTING.md` → the type → bump table and the enforcement note. -4. `open-pr.md` + `create-branch.md` → the list of types and the bump mapping. +- **Releasable units.** Stock release-please opens/updates a Release PR only for `feat`, `fix` and `deps` commits — plus anything marked breaking. Other types never trigger or bump a release by themselves. (`deps` is not in our commitlint enum; dependency bumps here land as `ci`/`chore` and therefore do not release.) +- **No per-type bump config.** Unlike semantic-release's `releaseRules`, release-please cannot map `chore` → patch. If a change must ship, give it a releasing type (`fix`/`feat`) — do not invent config that does not exist. +- **Squash-merge means the PR title is the commit.** Merges to `main` are squash merges (#795), so release-please parses the **PR title** as the conventional commit. The title must be commitlint-valid and carry the intended type; a breaking change belongs in the title as `!` — a `BREAKING CHANGE:` footer buried in the squashed body's bullet list is easy to lose. +- **Path filtering per package.** A commit counts toward a package's release only if it touches files under that package's path ([`release-please-config.json`](../../release-please-config.json)`#packages`). A `fix(webkit)` that only edits theme files bumps nothing for webkit. +- **`Release-As:` footer** overrides the computed version when an explicit version is required. +- **The Release PR is the release.** Merging a `feat`/`fix` updates the pending Release PR; merging the Release PR bumps versions, tags, and triggers the `package-*.yml` publish workflows via `release: published`. -No release? Use `{ "type": "", "release": false }` in `releaseRules` (do not omit the type). +## When adding, removing, or re-mapping a type -## `@semantic-release/commit-analyzer` details that matter +Make the edits **in the same PR**: -- The custom `releaseRules` is evaluated **before** `DEFAULT_RELEASE_RULES`; the default only kicks in when **no** custom rule matches (`isUndefined`). -- A custom rule with `release: false` returns `false` (not `undefined`), so it **suppresses** the default. This is how `revert` ends up with no release, instead of falling into the default `{ revert: true } → patch`. -- The rule `{ "breaking": true, "release": "major" }` is **always last** in the array. Because of `compareReleaseTypes`, an earlier `release: false` rule does not downgrade a breaking commit — `major` still wins. -- The analyzer also filters by path: a commit only counts toward a package's release if it touches files under `packages//`. +1. `commitlint.config.js` → `type-enum`. +2. `CONTRIBUTING.md` → the type table and the enforcement note. +3. `open-pr.md` + `create-branch.md` → the list of types and the release mapping. +4. If the intent is for a type to start releasing: that is **not** a config edit — release-please cannot express it. The change is "use `fix`/`feat` instead", and this rule + the docs must say so. ## What not to do -- Don't add a type to the command or to commitlint without adding it to the three `.releaserc` files. -- Don't touch only `webkit`'s `.releaserc` and forget `theme` / `icons`. -- Don't rely on the preset default for a type — list it explicitly. -- Don't let `CONTRIBUTING.md` describe a different bump than the one `releaseRules` produces. +- Don't add a type to the commands or to commitlint without updating CONTRIBUTING and the other command in the same PR. +- Don't document a bump release-please won't produce (the old `chore`/`docs`/`style`/`refactor`/`perf` → patch table died with semantic-release). +- Don't re-add `hotfix` (or any alias of `fix`) — a type whose name implies a release but never produces one is a trap; urgent fixes are `fix`. +- Don't reference `.releaserc` files — they were deleted with #798. +- Don't put a breaking change only in a commit footer of a multi-commit PR — put `!` in the PR title (squash merge). ## Why this rule exists -`/open-pr` and `/create-branch` listed `perf` / `test` / `ci` / `revert`, and `commitlint` accepted them, but the `.releaserc` files only enumerated seven types + breaking. `perf` only got a patch from the preset default and `test`/`ci`/`revert` did not appear — a divergence that earned a `CHANGES_REQUESTED`. Making the four points identical and explicit eliminates the entire class of bug. +`/open-pr` and `/create-branch` listed `perf` / `test` / `ci` / `revert`, and `commitlint` accepted them, but the (then) `.releaserc` files only enumerated seven types + breaking — a divergence that earned a `CHANGES_REQUESTED`. The same class of bug reappeared when #798 swapped semantic-release for release-please: this rule, CONTRIBUTING and the commands kept promising `hotfix`/`chore`/`docs`/`style`/`refactor`/`perf` → patch while stock release-please releases only on `feat`/`fix`/breaking. Rewritten 2026-07-26 to make release-please's real semantics the single documented truth across all four surfaces. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f5fcd0bbd..2d568c855 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,26 +95,27 @@ Opt a story out of the snapshot (it is still visited for render errors) with `pa ## Commit convention -We use [Conventional Commits](https://www.conventionalcommits.org/). `semantic-release` parses commit messages to compute version bumps and changelogs, so the scope and type matter. +We use [Conventional Commits](https://www.conventionalcommits.org/). Merges to `main` are **squash merges**, and [release-please](https://github.com/googleapis/release-please) parses the squashed commit — the **PR title** — to compute version bumps and changelogs through its Release PR, so the scope and type matter. -| Type | When | Bump | +| Type | When | Release | |---|---|---| | `feat` | New component, new prop/event/slot, new public export | minor | -| `fix` | Bug fix, accessibility correction, visual regression | patch | -| `hotfix` | Urgent production fix | patch | -| `chore` | Tooling, dependency bumps, internal cleanup | patch | -| `docs` | README, spec body, JSDoc | patch | -| `style` | Formatting / whitespace only | patch | -| `refactor` | Internal restructure with no API change | patch | -| `perf` | Performance improvement | patch | +| `fix` | Bug fix, accessibility correction, visual regression — anything that must ship (incl. urgent production fixes) | patch | +| `chore` | Tooling, dependency bumps, internal cleanup | none | +| `docs` | README, spec body, JSDoc | none | +| `style` | Formatting / whitespace only | none | +| `refactor` | Internal restructure with no API change | none | +| `perf` | Performance improvement (use `fix` if it must ship on its own) | none | | `test` | Test additions or changes | none | | `ci` | CI/CD pipeline changes | none | | `revert` | Reverting a prior commit | none | | `!` after type or `BREAKING CHANGE:` footer | Removed/renamed prop, event, slot, or export | major | +Types marked **none** never release on their own — they ride along in the next release cut by a `feat`/`fix`. Release-please cannot be configured to change this mapping; the full contract is [`.claude/rules/release-types.md`](./.claude/rules/release-types.md). + ### Message shape -The commit-analyzer regex in every `.releaserc` accepts these forms: +The commit parser accepts these forms: ```text [NO-ISSUE] fix(webkit): commit message @@ -136,22 +137,22 @@ Examples: Stay scoped: one package per commit when possible. Mixed-scope commits should use the broadest affected scope. -> Note: the analyzer also gates by file path. A commit must touch files under `packages//` for that package's `semantic-release` workflow to consider it. A `fix(webkit): …` commit that only edits theme files will not trigger a webkit release. +> Note: release-please also gates by file path. A commit must touch files under `packages//` to count toward that package's release. A `fix(webkit): …` commit that only edits theme files will not trigger a webkit release. ### Local enforcement -A husky `commit-msg` hook runs `@commitlint/cli` against [`commitlint.config.js`](./commitlint.config.js), which mirrors the regex in every `.releaserc`. A malformed message is rejected at commit time with a pointer to the failing rule — you cannot accidentally land a commit that the release analyzer would silently drop. +A husky `commit-msg` hook runs `@commitlint/cli` against [`commitlint.config.js`](./commitlint.config.js). A malformed message is rejected at commit time with a pointer to the failing rule. Because merges are squashed, keep the **PR title** commitlint-valid too — it is the commit release-please actually parses. The config also enforces: -- `type` must be one of: `feat`, `fix`, `hotfix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `ci`, `revert`. Every type is enumerated in each `.releaserc` `releaseRules`: the first eight produce a release (`feat` → minor, the rest → patch); `test`, `ci`, `revert` carry `release: false` for hygiene and produce no version bump. Breaking changes use the `!` marker or `BREAKING CHANGE:` footer and produce a `major` release. +- `type` must be one of: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `ci`, `revert`. Only `feat` (minor) and `fix` (patch) produce a release; every other type is accepted for hygiene and produces **no** version bump on its own. Breaking changes use the `!` marker or `BREAKING CHANGE:` footer and produce a `major` release on any type. (`hotfix` was removed 2026-07-26 — release-please never released it; use `fix`.) - `type` and `scope` must be lower-case. - `subject` cannot be empty. - Header (full first line) cannot exceed 100 characters. ## Pull requests -- Title mirrors the lead commit (Conventional Commits). +- Title mirrors the lead commit (Conventional Commits). Merges are squashed, so the **PR title is the commit** release-please parses — its type decides the release. - Body explains the **why** — screenshots for visual changes, before/after for behavior changes. - Link the spec (`.specs/.md`) for component PRs. - One feature per PR. Refactors and cleanups go in their own PRs. diff --git a/commitlint.config.js b/commitlint.config.js index 7fb921b54..485d6aa76 100644 --- a/commitlint.config.js +++ b/commitlint.config.js @@ -1,6 +1,7 @@ /** - * Commitlint config — mirrors the headerPattern in every packages/*\/.releaserc - * so a commit that passes locally also passes the semantic-release analyzer. + * Commitlint config — the commit-message gate for the repo. + * Merges to `main` are squash merges: release-please parses the squashed + * commit (the PR title), so keep PR titles commitlint-valid too. * * Accepted forms: * [NO-ISSUE] fix(webkit): commit message @@ -8,16 +9,17 @@ * fix(webkit): commit message * fix: commit message * - * Breaking changes (produce a major release per each .releaserc): + * Breaking changes (produce a major release): * feat(webkit)!: drop tone prop ← `!` after type/scope * feat(webkit): add x\n\nBREAKING CHANGE: drops y ← footer form * - * Type → release bump (final, after .releaserc rules + preset defaults): + * Type → release (stock release-please; not configurable per type): * feat → minor - * fix | hotfix | chore | docs | - * style | refactor | perf → patch - * test | ci | revert → no release (allowed for hygiene, no version bump) + * fix → patch + * chore | docs | style | refactor | + * perf | test | ci | revert → no release (allowed for hygiene, no version bump) * any-type with `!` or BREAKING: → major + * Contract: .claude/rules/release-types.md */ export default { parserPreset: { @@ -35,7 +37,6 @@ export default { [ 'feat', 'fix', - 'hotfix', 'chore', 'docs', 'style', diff --git a/packages/webkit/docs/DOC_LINTS.md b/packages/webkit/docs/DOC_LINTS.md index 8056c5038..133d3e6ff 100644 --- a/packages/webkit/docs/DOC_LINTS.md +++ b/packages/webkit/docs/DOC_LINTS.md @@ -1402,7 +1402,7 @@ Run `pnpm webkit:type-coverage` — `--detail` lists every offending expression. ## 10. commitlint — commit messages -Commits **drive releases**: `semantic-release` parses the same header to compute version bumps ([`release-types.md`](../../../.claude/rules/release-types.md)). Header anatomy: +Commits **drive releases**: release-please parses the same header — on `main`, the squashed **PR title** — to compute version bumps ([`release-types.md`](../../../.claude/rules/release-types.md)). Header anatomy: ``` [ENG-1231] feat(webkit)!: add table export @@ -1442,14 +1442,14 @@ feat(webkit): rework button size scale BREAKING CHANGE: size "xlarge" was removed; use "large". ``` -**Type → release bump** (must stay identical across `commitlint.config.js`, every `packages/*/.releaserc`, `CONTRIBUTING.md`, and the `/open-pr` / `/create-branch` flows): +**Type → release** (must stay identical across `commitlint.config.js`, release-please's stock semantics (`release-please-config.json`), `CONTRIBUTING.md`, and the `/open-pr` / `/create-branch` flows): -| Type | Bump | -| ------------------------------------------------------------------- | ------------------- | -| `feat` | **minor** | -| `fix` · `hotfix` · `chore` · `docs` · `style` · `refactor` · `perf` | **patch** | -| `test` · `ci` · `revert` | none (hygiene only) | -| any type with `!` or `BREAKING CHANGE:` footer | **major** | +| Type | Release | +| --------------------------------------------------------------------------- | ------------------- | +| `feat` | **minor** | +| `fix` | **patch** | +| `chore` · `docs` · `style` · `refactor` · `perf` · `test` · `ci` · `revert` | none (hygiene only) | +| any type with `!` or `BREAKING CHANGE:` footer | **major** | Also enforced: never `Co-Authored-By` / attribution footers, never `--no-verify` ([`git-workflow.md`](../../../.claude/rules/git-workflow.md)). diff --git a/packages/webkit/docs/PROCESS.md b/packages/webkit/docs/PROCESS.md index a1ccb9fd5..4cbef70aa 100644 --- a/packages/webkit/docs/PROCESS.md +++ b/packages/webkit/docs/PROCESS.md @@ -46,7 +46,7 @@ exists so the standard is applied _by construction_, not remembered by disciplin | 4 | Write-time gates | every `Write`/`Edit` | approved or `exit 2` | off-token, off-spec, phantom import, broken story | | 5 | PR + CI | `/create-branch` + `/open-pr` | PR to `dev` | any governance job fails | | 6 | Review | PR | 2 approvals (technical + design) | review-only surfaces off-pattern | -| 7 | Release | merge to `main` | semantic-release per package | commit type ⇄ bump divergence | +| 7 | Release | merge to `main` | release-please Release PR per package | commit type ⇄ bump divergence | ### Stage 1 — Specify @@ -261,30 +261,33 @@ Branch protection makes the approvals required; the PR cannot merge without them ### Stage 7 — Release -Merging to `main` runs semantic-release per package (`webkit`, `theme`, `icons`). The -Conventional Commit type decides the bump, and the type set is kept identical across -commitlint, every `.releaserc`, CONTRIBUTING, and the PR flows. +Merging to `main` updates a release-please Release PR per package (`webkit`, `theme`, +`icons`); merging that Release PR cuts the versions. Merges are squash merges, so the +Conventional Commit type in the **PR title** decides the bump, and the type set is kept +identical across commitlint, release-please, CONTRIBUTING, and the PR flows.
▸ Details — type → bump mapping and the four synchronized sources Per [release-types](../../../.claude/rules/release-types.md): -| Type | Bump | -| ------------------------------------------------------------------- | ----------------------- | -| `feat` | minor | -| `fix` / `hotfix` / `chore` / `docs` / `style` / `refactor` / `perf` | patch | -| `test` / `ci` / `revert` | none (`release: false`) | -| `!` or `BREAKING CHANGE:` | major | +| Type | Release | +| --------------------------------------------------------------------------- | ------------------- | +| `feat` | minor | +| `fix` | patch | +| `chore` / `docs` / `style` / `refactor` / `perf` / `test` / `ci` / `revert` | none (hygiene only) | +| `!` or `BREAKING CHANGE:` | major | +Stock release-please cannot remap types — anything that must ship is a `fix`/`feat`. The four places that carry this mapping — -[`commitlint.config.js`](../../../commitlint.config.js), every -`packages/*/.releaserc`, [`CONTRIBUTING.md`](../../../CONTRIBUTING.md), and the +[`commitlint.config.js`](../../../commitlint.config.js), +release-please (stock `release-type: node` in `release-please-config.json`), +[`CONTRIBUTING.md`](../../../CONTRIBUTING.md), and the `/open-pr` + `/create-branch` flows — must be edited **in the same PR** when a type is -added or re-mapped. The analyzer only counts a commit toward a package when it touches +added or removed. release-please only counts a commit toward a package when it touches files under that package. -At publish time `.releaserc`'s `prepareCmd` generates `.d.ts` files (`vue-tsc`); the +At publish time the publish workflow (`package-webkit.yml`) generates `.d.ts` files (`vue-tsc`); the repo itself ships source (`exports` points at `./src/...`) — `.d.ts` is never committed. The published package embeds [`catalog.json`](../catalog.json) — the version-locked manifest Part 2 runs on. diff --git a/packages/webkit/docs/STYLEGUIDE.md b/packages/webkit/docs/STYLEGUIDE.md index a634a4f1e..49ea77811 100644 --- a/packages/webkit/docs/STYLEGUIDE.md +++ b/packages/webkit/docs/STYLEGUIDE.md @@ -625,11 +625,12 @@ Internal to the webkit repo — how its own components come to exist. ## 21. Releases & git -- **Conventional Commits**, with one canonical type→bump set kept identical across - commitlint, every package `.releaserc`, CONTRIBUTING, and the PR commands: - `feat` → minor · `fix`/`hotfix`/`chore`/`docs`/`style`/`refactor`/`perf` → patch · - `test`/`ci`/`revert` → no release · `!`/`BREAKING CHANGE:` → major. -- Branch from **`dev`**, PR to `dev`; branches named `/-`; shared +- **Conventional Commits**, with one canonical type→release set kept identical across + commitlint, release-please, CONTRIBUTING, and the PR commands: + `feat` → minor · `fix` → patch · `chore`/`docs`/`style`/`refactor`/`perf`/`test`/`ci`/`revert` + → no release on their own · `!`/`BREAKING CHANGE:` → major. Merges are squashed — the + **PR title** is the commit release-please parses. +- Branch from **`main`**, PR to `main`; branches named `/-`; shared docs/rules in a separate PR from component code. - Reshaping any public contract (prop/event/model/payload) is a **major**, updating spec, argTypes, and "Show code" together.