From 49eba0e7fa59ef506173f520c9849f98e794c199 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jakub=20=C5=A0alm=C3=ADk?= <som@jakubsalmik.com>
Date: Thu, 14 May 2026 10:18:06 +0200
Subject: [PATCH] chore: add contributing guide and changeset CI check

Add a Contributing section to the README covering branch flow,
pre-push checks, changesets, and how the Release workflow handles
versioning/publishing. Add a PR workflow that fails when src/ is
modified without a changeset, so contributors get a clear signal
before merge instead of silently shipping a change without a bump.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/changeset-check.yml | 50 +++++++++++++++++++++++++++
 README.md                             | 23 ++++++++++++
 2 files changed, 73 insertions(+)
 create mode 100644 .github/workflows/changeset-check.yml

diff --git a/.github/workflows/changeset-check.yml b/.github/workflows/changeset-check.yml
new file mode 100644
index 0000000..a1a6018
--- /dev/null
+++ b/.github/workflows/changeset-check.yml
@@ -0,0 +1,50 @@
+name: Changeset check
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  changeset:
+    name: Require changeset for src/ changes
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check for changeset
+        run: |
+          BASE="origin/${{ github.base_ref }}"
+          git fetch origin "${{ github.base_ref }}" --depth=1
+
+          SRC_CHANGED=$(git diff --name-only "$BASE"...HEAD -- 'src/**' || true)
+          NEW_CHANGESETS=$(git diff --name-only --diff-filter=A "$BASE"...HEAD -- '.changeset/*.md' \
+            | grep -v '^.changeset/README.md$' || true)
+
+          if [ -z "$SRC_CHANGED" ]; then
+            echo "No changes under src/ — changeset not required."
+            exit 0
+          fi
+
+          echo "Files changed under src/:"
+          echo "$SRC_CHANGED"
+          echo ""
+
+          if [ -z "$NEW_CHANGESETS" ]; then
+            echo "::error::This PR changes files under src/ but does not include a changeset."
+            echo ""
+            echo "Run 'npx changeset' locally, pick a bump type (patch/minor/major),"
+            echo "write a one-line summary from the consumer's perspective, then commit"
+            echo "the generated .changeset/*.md file."
+            echo ""
+            echo "If this change truly has no user-facing effect (e.g. an internal-only"
+            echo "refactor mistakenly placed under src/), explain in the PR description"
+            echo "and a maintainer can override this check."
+            exit 1
+          fi
+
+          echo "Found changeset(s):"
+          echo "$NEW_CHANGESETS"
diff --git a/README.md b/README.md
index c7282fa..a544732 100644
--- a/README.md
+++ b/README.md
@@ -59,6 +59,29 @@ All tokens are also exposed as CSS variables (`--snake-loader-snake`, `--snake-l
 - `role="progressbar"` with `aria-busy="true"` and an `aria-label` (defaults to "Loading").
 - Respects `prefers-reduced-motion` — halves tick speed, disables pulse/trail.
 
+## Contributing
+
+PRs welcome.
+
+1. Branch off `main` — `fix/...`, `feat/...`, `chore/...`, or `docs/...`. `main` is protected.
+2. Before pushing, run `npm run typecheck` and `npm run build`. Both must pass.
+3. If your change touches `src/`, add a changeset:
+   ```bash
+   npx changeset
+   ```
+   Pick `patch` (bug fix), `minor` (additive feature), or `major` (breaking change), and write a one-line summary from the consumer's perspective. CI fails without one.
+4. Open a PR with `gh pr create`.
+
+### Release automation
+
+You don't run `npm publish`, `npm version`, or tag releases by hand.
+
+- Merging a PR to `main` runs the [Release workflow](.github/workflows/release.yml).
+- If pending changesets exist, it opens (or updates) a "version packages" PR that bumps `package.json` and updates `CHANGELOG.md`.
+- Merging that PR publishes to npm and tags the release.
+
+Don't commit `dist/` or `node_modules/`, don't edit changeset files in the version PR, and don't add runtime dependencies — this package is zero-deps.
+
 ## License
 
 MIT © [Jakub Šalmík](https://jakubsalmik.com)