chore: document master/dev/next branch model + wire CI triggers (#709)

Author: johnleider

.github/workflows/changeset-reminder.yml

@@ -10,7 +10,7 @@ name: Changeset reminder
 # comments — no untrusted PR code is ever checked out or executed.
 on:
   pull_request_target:
-    branches: [master]
+    branches: [master, dev, next]
     types: [opened, synchronize, reopened]
 
 permissions:
@@ -24,7 +24,7 @@ jobs:
   remind:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6 # base branch (master) — trusted, NOT the PR head
+      - uses: actions/checkout@v6 # PR base branch (master/dev/next) — trusted, NOT the PR head
       - name: Changeset reminder
         env:
           GH_TOKEN: ${{ github.token }}

.github/workflows/pr-checks.yml

@@ -2,9 +2,9 @@ name: PR Checks
 
 on:
   pull_request:
-    branches: [master]
+    branches: [master, dev, next]
   push:
-    branches: [master]
+    branches: [master, dev, next]
 
 permissions:
   contents: read

.github/workflows/release.yml

@@ -2,6 +2,10 @@ name: Release
 
 on:
   push:
+    # master is the sole release branch. Under the master/dev/next model,
+    # `dev` (features/minor) and `next` (breaking/major) accumulate work and
+    # merge INTO master at each minor/major cut — the merge is what triggers
+    # publishing. Do NOT add dev/next here; they must not publish directly.
     branches:
       - master
 

CLAUDE.md

@@ -94,6 +94,7 @@ pnpm changeset        # Author a changeset for your PR (run per change)
 pnpm release:prepare  # Pre-release validation (validate + build)
 # Publishing is automated: pushing to master opens a "Version Packages" PR;
 # merging it builds, publishes to npm via OIDC, and creates the GitHub releases.
+# Base branch by change type: fix/patch → master, feat/minor → dev, breaking/major → next.
 # Currently in PRE mode (beta dist-tag) — see "Releasing" below before cutting stable.
 
 # Repo health
@@ -104,6 +105,21 @@ pnpm repo:check       # knip + sherif
 
 Changesets-driven. Pushing to `master` opens/updates a "Version Packages" PR; merging it publishes to npm (tokenless OIDC) and mints the GitHub releases (`.github/workflows/release.yml`).
 
+### Branch model — where a PR goes by change type
+
+Three long-lived branches; a PR's base is chosen by the semver impact of the change, not by its commit-type label alone:
+
+| Base | Change type | Semver | Examples |
+|------|-------------|--------|----------|
+| `master` | fixes, docs, chore, refactor, tests | patch / none | `fix(...)`, `docs(...)`, `test(...)`, and any app/tooling change that ships no package version |
+| `dev` | new features that add public API | minor | `feat(...)` that adds a component, composable, prop, or option |
+| `next` | breaking changes | major | anything with a `BREAKING CHANGE:` footer |
+
+- **Only `master` publishes.** `dev` and `next` accumulate work and merge **into `master`** at the next minor / major cut — that merge is what triggers the changesets release. Never publish from `dev`/`next` directly.
+- **`feat`/`fix` are still reserved for `packages/*` source.** A `feat(docs)` / `feat(playground)` / app-only change ships no package version, so it targets `master` (patch train) regardless of the `feat` label — prefer `docs`/`chore` for those.
+- **Design systems** (`@paper/*`) version independently; a DS feature still targets `dev` (it's a minor bump for that package).
+- CI (`pr-checks.yml`) and the changeset reminder (`changeset-reminder.yml`) run on PRs into all three branches; `release.yml` triggers on `master` pushes only.
+
 ### Changeset content contract
 
 The `.changeset/*.md` body renders verbatim into the changelog and GitHub release notes — it is release-note copy, not a commit message. Don't budget by character count; budget by what belongs:

apps/docs/src/pages/introduction/contributing.md

@@ -114,9 +114,25 @@ pnpm build            # Build packages
 
 ## Pull Requests
 
+### Branch Model
+
+`@vuetify/v0` uses three long-lived branches. Open your PR against the base that matches the **semver impact** of your change:
+
+| Base | Use it for | Release |
+|------|-----------|---------|
+| `master` | Bug fixes, docs, chores, refactors, tests | Patch (or no version bump) |
+| `dev` | New features that add public API (a component, composable, prop, or option) | Minor |
+| `next` | Breaking changes (anything with a `BREAKING CHANGE:` footer) | Major |
+
+Only `master` publishes to npm. Work on `dev` and `next` merges into `master` at the next minor or major release, and that merge is what ships it. If you're unsure which base fits, open against `master` — a maintainer will retarget it.
+
+::: tip
+A `feat` that only touches the docs site, playground, or other tooling (not `packages/*` source) ships no package version, so it targets `master` — prefer a `docs`/`chore` prefix for those.
+:::
+
 ### Before Submitting
 
-1. Create a new branch from `master`
+1. Create a new branch from the right base for your change (see [Branch Model](#branch-model)): `master` for fixes, `dev` for features, `next` for breaking changes
 2. Make your changes
 3. Write tests for new functionality
 4. Run `pnpm lint:fix` to fix formatting
@@ -166,12 +182,14 @@ Never edit `package.json` versions by hand — release automation owns every bum
 
 ### Branch Naming
 
-Use descriptive branch names:
+Use descriptive branch names; the prefix should match the base branch you target (see [Branch Model](#branch-model)):
+
+- `fix/issue-description` - Bug fixes → base `master`
+- `feat/feature-name` - New features → base `dev`
+- `docs/what-changed` - Documentation updates → base `master`
+- `refactor/what-changed` - Code refactoring → base `master`
 
-- `fix/issue-description` - Bug fixes
-- `feat/feature-name` - New features
-- `docs/what-changed` - Documentation updates
-- `refactor/what-changed` - Code refactoring
+Breaking changes target `next` regardless of prefix.
 
 ## Commit Messages