ci(release): adopt changesets for versioning and release notes

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.changeset/initial-changesets-adoption.md

@@ -0,0 +1,5 @@
+---
+"lens": patch
+---
+
+Adopt changesets for versioning and release notes. Adds `@changesets/cli`, a release GitHub Actions workflow that opens a "Version Packages" PR for pending changesets and tags releases on merge, and contributor docs for the workflow.

.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+# Opens (or updates) a "Version Packages" PR whenever there are pending
+# changesets on main. When that PR is merged, the version is bumped and a
+# matching git tag + GitHub release is created.
+#
+# Lens is not published to npm, so there is no `npm publish` step — the
+# release step runs `changeset tag`, which only creates git tags.
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release:
+    name: Version / Tag
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Full history is required so changesets can read tags.
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci || npm install
+
+      - name: Create Version PR or tag release
+        uses: changesets/action@v1
+        with:
+          # Opens/updates the "Version Packages" PR when changesets are pending.
+          version: npm run version-packages
+          # Runs once the Version PR is merged (no changesets left). Creates git
+          # tags only — Lens is not on npm, so nothing is published to a registry.
+          publish: npm run release
+          commit: 'ci(release): version packages'
+          title: 'ci(release): version packages'
+          createGithubReleases: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

CONTRIBUTING.md

@@ -70,6 +70,28 @@ npm test --if-present
 
 Tests are being set up — see [`area:tests`](https://github.com/Miracle656/Lens/labels/area%3Atests). Candidates: route handlers, price math, x402 flow, ingester bisection, DB queries.
 
+## Releases
+
+Lens uses [changesets](https://github.com/changesets/changesets) for versioning and changelog generation.
+
+### Adding a changeset
+
+When you make a change that should appear in the changelog (a feature, fix, or any user-facing change), add a changeset in the same PR:
+
+```bash
+npx changeset
+```
+
+Pick the bump type (`patch` / `minor` / `major`) and write a short summary. This creates a markdown file under `.changeset/` — commit it alongside your change.
+
+### How a release happens
+
+1. When PRs with changesets are merged into `main`, the release workflow (`.github/workflows/release.yml`) opens (or updates) a **"Version Packages"** PR.
+2. That PR consumes the pending changeset files, bumps the version in `package.json`, and updates `CHANGELOG.md`.
+3. Merging the Version Packages PR bumps the version and creates a matching git tag and GitHub release.
+
+Lens is not published to a registry, so there is no publish step — releases are tag-only (`changeset tag`).
+
 ## Questions
 
 Open an [issue](https://github.com/Miracle656/Lens/issues) or start a [discussion](https://github.com/Miracle656/Lens/discussions).