Add changesets and automated release workflow

Copilot · hotlong · Copilot · commit a7a47e898f2f · 2026-01-15T07:41:54.000Z
- Install @changesets/cli package
- Configure changesets for monorepo (ignore examples/apps, public access)
- Add changeset scripts to package.json
- Create GitHub Actions workflow for automated releases
- Update CONTRIBUTING.md with changeset usage guide
- Update .github/WORKFLOWS.md with changeset documentation
- Enhance .changeset/README.md with Object UI specific guidance

Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/.changeset/README.md b/.changeset/README.md
@@ -0,0 +1,73 @@
+# Changesets
+
+This directory contains changeset files that track changes to packages in the Object UI monorepo.
+
+## What are Changesets?
+
+Changesets are a way to declare your intent to release packages. They help us:
+- Track which packages have changed
+- Determine appropriate version bumps (major, minor, patch)
+- Generate comprehensive changelogs
+- Automate the release process
+
+## Quick Start
+
+### Creating a Changeset
+
+When you make changes to packages, run:
+
+```bash
+pnpm changeset
+```
+
+This will guide you through:
+1. Selecting which packages changed
+2. Choosing the type of version bump
+3. Writing a description of the changes
+
+### Example
+
+```bash
+$ pnpm changeset
+
+🦋  Which packages would you like to include?
+◉ @object-ui/react
+◯ @object-ui/core
+◯ @object-ui/components
+
+🦋  What kind of change is this for @object-ui/react?
+◯ major (breaking change)
+◉ minor (new feature)
+◯ patch (bug fix)
+
+🦋  Please enter a summary for this change:
+Add support for custom validators in form components
+```
+
+### When to Create a Changeset
+
+✅ **DO** create a changeset for:
+- New features
+- Bug fixes
+- Breaking changes
+- Performance improvements
+- API changes
+
+❌ **DON'T** create a changeset for:
+- Documentation updates
+- Changes to examples or apps
+- Internal refactoring with no API changes
+- Test-only updates
+
+## Automated Release Process
+
+1. **Merge PR with changeset** → Triggers automation
+2. **Bot creates "Version Packages" PR** → Updates versions and changelogs
+3. **Merge Version PR** → Automatically publishes to npm
+
+## Learn More
+
+- [Full Changesets Documentation](https://github.com/changesets/changesets)
+- [Object UI Contributing Guide](../CONTRIBUTING.md#versioning-and-releases)
+- [Common Questions](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
+
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": [
+    "@apps/*",
+    "@examples/*"
+  ]
+}
diff --git a/.github/WORKFLOWS.md b/.github/WORKFLOWS.md
@@ -121,7 +121,58 @@ Creates GitHub releases and publishes packages.
 
 **Note**: npm publishing is currently disabled. Uncomment the publish step when ready.
 
-### 8. Stale Issues & PRs
+### 8. Changeset Release (Automated)
+
+**File**: `changeset-release.yml`  
+**Triggers**: Push to `main` branch
+
+Automated version management and package publishing using Changesets.
+
+**What It Does**:
+1. Detects changesets in merged PRs
+2. Creates/updates a "Version Packages" PR that:
+   - Bumps package versions based on changesets
+   - Updates CHANGELOG.md files
+   - Removes consumed changeset files
+3. When the Version PR is merged:
+   - Publishes updated packages to npm
+   - Creates GitHub releases with tags
+
+**How It Works**:
+
+```mermaid
+graph LR
+    A[PR with changeset merged] --> B[Workflow runs]
+    B --> C{Changesets exist?}
+    C -->|Yes| D[Create/Update Version PR]
+    C -->|No| E[Skip]
+    D --> F[Version PR merged]
+    F --> G[Publish to npm]
+    G --> H[Create GitHub Release]
+```
+
+**Developer Workflow**:
+1. Create PR with code changes
+2. Run `pnpm changeset` to create a changeset file
+3. Commit changeset file with your PR
+4. When PR is merged, automation takes over
+5. Review and merge the automated "Version Packages" PR
+6. Packages are published automatically
+
+**Benefits**:
+- No manual version number editing
+- Automatic changelog generation
+- Coordinated releases across packages
+- Clear versioning based on semantic versioning
+- Prevents accidental version conflicts
+
+**Required Setup**:
+- `NPM_TOKEN` secret must be configured in repository settings
+- Changesets should be included in all PRs with package changes
+
+**Note**: See [CONTRIBUTING.md](../CONTRIBUTING.md#versioning-and-releases) for details on creating changesets.
+
+### 9. Stale Issues & PRs
 
 **File**: `stale.yml`  
 **Triggers**: Daily schedule, Manual workflow dispatch
@@ -134,7 +185,7 @@ Manages stale issues and pull requests.
 - Exempt labels: `pinned`, `security`, `critical`, `bug`, `enhancement`
 - Can be reopened if activity resumes
 
-### 9. Dependabot Auto-merge
+### 10. Dependabot Auto-merge
 
 **File**: `dependabot-auto-merge.yml`  
 **Configuration**: `dependabot.yml`  
@@ -153,7 +204,7 @@ Automatically manages dependency updates.
 - Groups related dependencies
 - Limits to 10 open PRs
 
-### 10. Auto Changelog
+### 11. Auto Changelog
 
 **File**: `changelog.yml`  
 **Triggers**: Release published, Manual workflow dispatch
diff --git a/.github/workflows/changeset-release.yml b/.github/workflows/changeset-release.yml
@@ -0,0 +1,57 @@
+name: Changeset Release
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release:
+    name: Changeset Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Build packages
+        run: pnpm build
+
+      - name: Create Release Pull Request or Publish to npm
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          version: pnpm changeset:version
+          publish: pnpm changeset:publish
+          title: 'chore: release packages'
+          commit: 'chore: release packages'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -303,19 +303,31 @@ refactor: simplify expression evaluator
    git rebase upstream/main
    ```
 
-2. **Ensure tests pass**:
+2. **Create a changeset** (for package changes):
+   ```bash
+   pnpm changeset
+   ```
+   
+   This will prompt you to:
+   - Select which packages have changed
+   - Choose the version bump type (major, minor, patch)
+   - Write a summary of the changes
+   
+   Learn more about changesets in the [Versioning and Releases](#versioning-and-releases) section.
+
+3. **Ensure tests pass**:
    ```bash
    pnpm test
    ```
 
-3. **Ensure build succeeds**:
+4. **Ensure build succeeds**:
    ```bash
    pnpm build
    ```
 
-4. **Update documentation** if needed
+5. **Update documentation** if needed
 
-5. **Add tests** for new features
+6. **Add tests** for new features
 
 ### Creating the PR
 
@@ -398,6 +410,121 @@ pnpm docs:build
 
 See [Documentation Guide](./docs/README.md) for details.
 
+## Versioning and Releases
+
+We use [Changesets](https://github.com/changesets/changesets) for version management and automated releases.
+
+### Understanding Changesets
+
+Changesets is a tool that helps us:
+- **Track changes**: Each PR includes a changeset file describing what changed
+- **Automate versioning**: Automatically determine version bumps based on changesets
+- **Generate changelogs**: Create comprehensive changelogs from changeset descriptions
+- **Coordinate releases**: Release multiple packages together in our monorepo
+
+### When to Create a Changeset
+
+Create a changeset when your PR makes changes to any package in `packages/`:
+
+- ✅ **DO create a changeset for**:
+  - New features
+  - Bug fixes
+  - Breaking changes
+  - Performance improvements
+  - API changes
+
+- ❌ **DON'T create a changeset for**:
+  - Documentation updates only
+  - Changes to examples or apps
+  - Internal refactoring with no user-facing changes
+  - Test updates without code changes
+
+### How to Create a Changeset
+
+1. **Run the changeset command**:
+   ```bash
+   pnpm changeset
+   ```
+
+2. **Select packages**: Use arrow keys and spacebar to select which packages changed
+   ```
+   🦋  Which packages would you like to include?
+   ◯ @object-ui/core
+   ◉ @object-ui/react
+   ◯ @object-ui/components
+   ```
+
+3. **Choose version bump type**:
+   - **Major** (x.0.0): Breaking changes
+   - **Minor** (0.x.0): New features (backwards compatible)
+   - **Patch** (0.0.x): Bug fixes and minor updates
+
+4. **Write a summary**: Describe what changed
+   ```
+   Summary: Add support for custom validation rules in forms
+   ```
+
+5. **Commit the changeset file**:
+   ```bash
+   git add .changeset/*.md
+   git commit -m "chore: add changeset"
+   ```
+
+### Changeset Message Guidelines
+
+Write clear, user-facing descriptions:
+
+```markdown
+✅ Good:
+- Add support for custom date formats in DatePicker
+- Fix validation error in nested form fields
+- Improve performance of large data grids by 50%
+
+❌ Bad:
+- Updated code
+- Fixed bug
+- Changes to validation
+```
+
+### Release Process
+
+The release process is automated:
+
+1. **Create PR with changes** → Include a changeset file
+2. **PR is merged** → Changeset bot creates/updates a "Version Packages" PR
+3. **Version PR is merged** → Packages are automatically published to npm
+
+You don't need to manually:
+- Update version numbers
+- Update CHANGELOGs
+- Create Git tags
+- Publish to npm
+
+Everything is handled by the changeset automation!
+
+### Example Workflow
+
+```bash
+# 1. Create a feature branch
+git checkout -b feat/add-date-picker
+
+# 2. Make your changes
+# ... edit files ...
+
+# 3. Create a changeset
+pnpm changeset
+# Select @object-ui/components
+# Choose "minor" (new feature)
+# Summary: "Add DatePicker component with calendar popup"
+
+# 4. Commit everything
+git add .
+git commit -m "feat: add DatePicker component"
+
+# 5. Push and create PR
+git push origin feat/add-date-picker
+```
+
 ## Adding Components
 
 ### Creating a New Component
diff --git a/package.json b/package.json
@@ -30,9 +30,13 @@
     "test:coverage": "vitest run --coverage",
     "lint": "pnpm -r lint",
     "cli": "node packages/cli/dist/cli.js",
-    "objectui": "node packages/cli/dist/cli.js"
+    "objectui": "node packages/cli/dist/cli.js",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "changeset:publish": "changeset publish"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.29.8",
     "@eslint/js": "^9.39.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
