feat(ci): automate releases with changesets

.changeset/config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
+  "changelog": [
+    "@changesets/changelog-github",
+    { "repo": "rstackio/services" }
+  ],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.changeset/nine-mugs-enjoy.md

@@ -0,0 +1,2 @@
+---
+---

.github/workflows/ci.yml

@@ -30,6 +30,9 @@ jobs:
       - name: Check deps
         run: pnpm check:deps
 
+      - name: Check changeset
+        run: pnpm changeset status --since origin/${{ github.base_ref }}
+
       - name: Resolve changed files
         run: |
           set -eo pipefail  # fail fast: exit on error (-e) and propagate pipe failures (-o pipefail)

.github/workflows/publish.yml

@@ -9,12 +9,16 @@ jobs:
     name: Publish
     runs-on: ubuntu-latest
     environment: Publish
+    # skip when the pipeline itself pushes the version bump commit
+    if: "!contains(github.event.head_commit.message, 'chore: release')"
     permissions:
-      contents: write # required for pushing git tags
+      contents: write # required for pushing commits, tags and creating GitHub releases
       id-token: write # required for npm provenance
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - uses: pnpm/action-setup@v4
 
@@ -61,23 +65,45 @@ jobs:
       - name: Build
         run: pnpm build
 
-      - name: Publish if new version
-        id: publish
+      - name: Apply changesets
+        id: version
         run: |
-          PKG_VERSION=$(node -p "require('./package.json').version")
-          if npm view @rstackio/services@$PKG_VERSION version > /dev/null 2>&1; then
-            echo "Version $PKG_VERSION already published, skipping"
-            echo "published=false" >> $GITHUB_OUTPUT
+          pnpm changeset version
+          if git diff --quiet package.json; then
+            echo "changed=false" >> $GITHUB_OUTPUT
           else
-            pnpm publish --no-git-checks --access public --provenance
-            echo "published=true" >> $GITHUB_OUTPUT
+            PKG_VERSION=$(node -p "require('./package.json').version")
+            echo "changed=true" >> $GITHUB_OUTPUT
             echo "version=$PKG_VERSION" >> $GITHUB_OUTPUT
           fi
+
+      - name: Publish to npm
+        if: steps.version.outputs.changed == 'true'
+        run: pnpm release
         env:
           NODE_AUTH_TOKEN: ${{ secrets.RSTACKIO_NPM_TOKEN }}
 
+      - name: Commit version bump
+        if: steps.version.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .
+          git commit -m "chore: release v${{ steps.version.outputs.version }}"
+          git push
+
+      - name: Create GitHub release
+        if: steps.version.outputs.changed == 'true'
+        run: |
+          VERSION="v${{ steps.version.outputs.version }}"
+          git tag $VERSION
+          git push origin $VERSION
+          gh release create $VERSION --generate-notes --title "$VERSION"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
       - name: Update coverage badge
-        if: steps.publish.outputs.published == 'true'
+        if: steps.version.outputs.changed == 'true'
         continue-on-error: true
         uses: schneegans/dynamic-badges-action@v1.7.0
         with:
@@ -87,9 +113,3 @@ jobs:
           label: coverage
           message: ${{ steps.coverage.outputs.pct }}%
           color: ${{ steps.coverage.outputs.color }}
-
-      - name: Push git tag
-        if: steps.publish.outputs.published == 'true'
-        run: |
-          git tag "v${{ steps.publish.outputs.version }}"
-          git push origin "v${{ steps.publish.outputs.version }}"

CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+## Setup
+
+```sh
+pnpm install
+pnpm test:watch   # run tests in watch mode
+pnpm dev          # watch mode — rebuilds on file changes
+```
+
+## Making a PR
+
+### 1. Make your changes
+
+Write code, add or update tests, update docs if needed.
+
+### 2. Add a changeset
+
+Every PR that touches source code **must include a changeset** — CI will fail without one.
+
+```sh
+pnpm changeset
+```
+
+This opens an interactive prompt:
+
+```text
+🦋  What kind of change is this for @rstackio/services?
+  ❯ patch  — bug fix, dependency update, internal refactor
+    minor  — new backwards-compatible feature
+    major  — breaking change
+```
+
+Pick the bump type, write a short description of what changed and why (this becomes the CHANGELOG entry), then commit the generated `.changeset/*.md` file with your PR.
+
+### 3. Commit message format
+
+This repo uses [Conventional Commits](https://www.conventionalcommits.org/):
+
+```text
+<type>(<scope>): <description>
+
+feat(data-provider): add andFinally() chain method
+fix(mock): handle AbortSignal on delay cancel
+docs: update usage examples
+chore: upgrade typescript to 5.9
+```
+
+Common types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`.
+
+### 4. Open the PR
+
+CI runs types, deps, linting, tests, and the changeset check automatically.
+
+---
+
+## Release flow
+
+Releases are fully automated — you don't need to bump versions or publish manually.
+
+When your PR is merged to `main`, the publish pipeline runs automatically:
+1. It applies all pending changesets — bumps the version in `package.json` and generates `CHANGELOG.md`.
+2. Commits the version bump directly to `main` and publishes the package to npm.

README.md

@@ -138,7 +138,7 @@ Requires **TypeScript 5.0+** with `strict: true`.
 
 ---
 
-## 🛠️ Development
+## 🛠️ Contributing
 
 ```sh
 pnpm install
@@ -147,6 +147,8 @@ pnpm test:watch    # watch mode
 pnpm build         # build dist
 ```
 
+See [CONTRIBUTING.md](https://github.com/rstackio/services/blob/main/CONTRIBUTING.md) for the full guide, including how to add a changeset to your PR.
+
 ---
 
 ## 👥 Contributors

package.json

@@ -54,6 +54,7 @@
   ],
   "scripts": {
     "build": "rslib build",
+    "changeset": "changeset",
     "check:deps": "knip",
     "check:types": "tsc --noEmit",
     "dev": "rslib build --watch",
@@ -62,6 +63,7 @@
     "preinstall": "npx only-allow pnpm",
     "lint": "biome lint --write",
     "prepare": "simple-git-hooks",
+    "release": "pnpm publish --access public --provenance --no-git-checks",
     "test": "rstest run",
     "test:coverage": "rstest run --coverage",
     "test:related": "rstest run --passWithNoTests",
@@ -82,6 +84,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8",
     "@commitlint/cli": "^20.4.2",
     "@commitlint/config-conventional": "^20.4.2",
     "@rslib/core": "^0.19.6",