feat: implement changesets for selective package versioning

.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/[email protected]/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "next",
+  "updateInternalDependencies": "patch",
+  "ignore": ["helloworld-*", "site"]
+}

.github/workflows/changesets.yml

@@ -0,0 +1,76 @@
+name: Changesets Release
+
+on:
+  push:
+    branches:
+      - next
+
+concurrency:
+  group: changesets-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+  pull-requests: write
+
+jobs:
+  release:
+    name: Changesets Release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcb5dd907a8 # v5
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GIT_TOKEN }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@41ff72655975bd51cab0327fa583b6e92b6d3061 # v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6
+        with:
+          node-version: '24'
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Re-install npm
+        # TODO: OIDC requires npm >=11.5.1.
+        # Until Node.js v24 is LTS (with npm 11 as the default), we need to bump.
+        run: npm install -g npm@11
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Configure Git
+        run: |
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+
+      - name: Create Release Pull Request or Publish
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          version: pnpm run changeset:version
+          publish: pnpm run changeset:publish
+          commit: 'chore(release): version packages'
+          title: 'chore(release): version packages'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GIT_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true
+
+      - name: Sync to cnpm
+        if: steps.changesets.outputs.published == 'true'
+        run: node scripts/sync-cnpm.js
+
+      - name: Summary
+        if: steps.changesets.outputs.published == 'true'
+        run: |
+          echo "## 🎉 Release Summary" >> $GITHUB_STEP_SUMMARY
+          echo "### ✅ Packages Published" >> $GITHUB_STEP_SUMMARY
+          echo '```json' >> $GITHUB_STEP_SUMMARY
+          echo '${{ steps.changesets.outputs.publishedPackages }}' >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY

README.md

@@ -65,6 +65,22 @@ pnpm --filter=@examples/helloworld-typescript run dev
 pnpm --filter=site run dev
 ```
 
+### Version Management
+
+This monorepo uses [changesets](https://github.com/changesets/changesets) for version management and publishing. This allows for:
+
+- **Selective releases**: Only changed packages are versioned and published
+- **Automatic changelogs**: Generated from changeset summaries
+- **Better tracking**: Clear documentation of what changed and why
+
+To add a changeset for your changes:
+
+```bash
+pnpm changeset
+```
+
+For detailed information, see our [Changeset Guide](docs/changeset-guide.md).
+
 ## Documentations
 
 - [Documentations](https://eggjs.org/)

README.zh-CN.md

@@ -34,6 +34,51 @@ pnpm run dev
 open http://localhost:7001
 ```
 
+## Monorepo 结构
+
+本项目使用 pnpm monorepo 结构，包含以下包：
+
+- `packages/egg` - Eggjs 主框架
+- `examples/helloworld-commonjs` - CommonJS 示例应用
+- `examples/helloworld-typescript` - TypeScript 示例应用
+- `site` - 文档网站
+
+该 monorepo 使用 **pnpm catalog mode** 进行集中式依赖管理，确保所有包之间的版本一致性。
+
+### 开发命令
+
+```bash
+# 安装所有包的依赖
+pnpm install
+
+# 构建所有包
+pnpm run build
+
+# 测试所有包
+pnpm run test
+
+# 运行特定包的命令
+pnpm --filter=egg run test
+pnpm --filter=@examples/helloworld-typescript run dev
+pnpm --filter=site run dev
+```
+
+### 版本管理
+
+本 monorepo 使用 [changesets](https://github.com/changesets/changesets) 进行版本管理和发布。这带来了以下好处：
+
+- **选择性发布**：只对变更的包进行版本升级和发布
+- **自动生成变更日志**：从 changeset 摘要自动生成
+- **更好的追踪**：清晰记录变更内容和原因
+
+为你的更改添加 changeset：
+
+```bash
+pnpm changeset
+```
+
+详细信息请查看我们的 [Changeset 使用指南](docs/changeset-guide.zh-CN.md)。
+
 ## 文档
 
 - [官方文档](https://eggjs.org/zh-CN/)

docs/changeset-guide.md

@@ -0,0 +1,194 @@
+# Changeset Guide for Egg.js Monorepo
+
+This document explains how to use changesets for version management and releasing packages in the Egg.js monorepo.
+
+## What are Changesets?
+
+Changesets is a tool designed for managing versions and changelogs in multi-package repositories (monorepos). It allows you to:
+
+- Track which packages need to be released
+- Version packages independently instead of bulk releases
+- Generate changelogs automatically
+- Publish only the packages that have changed
+
+## Basic Workflow
+
+### 1. Making Changes
+
+When you make changes to packages in the monorepo that should be released:
+
+```bash
+# Create a changeset describing your changes
+pnpm changeset
+```
+
+This will:
+
+1. Prompt you to select which packages have changed
+2. Ask for the version bump type (major, minor, or patch) for each package
+3. Prompt you to write a summary of the changes
+4. Create a markdown file in `.changeset/` with your changeset information
+
+### 2. Changeset Types
+
+When creating a changeset, you'll need to specify the version bump type:
+
+- **major**: Breaking changes (e.g., `1.0.0` → `2.0.0`)
+- **minor**: New features, backwards compatible (e.g., `1.0.0` → `1.1.0`)
+- **patch**: Bug fixes, backwards compatible (e.g., `1.0.0` → `1.0.1`)
+
+### 3. Committing Changesets
+
+Commit the generated changeset files along with your code changes:
+
+```bash
+git add .changeset/
+git commit -m "feat: add new feature"
+```
+
+### 4. Automated Release Process
+
+Once your PR is merged to the `next` branch:
+
+1. The GitHub Actions workflow automatically runs
+2. If changesets exist, it creates a "Version Packages" PR
+3. The Version Packages PR will:
+   - Update package versions based on changesets
+   - Update CHANGELOG.md files
+   - Remove consumed changesets
+4. When you merge the Version Packages PR, packages are automatically published to npm
+
+## Manual Commands
+
+### Creating a Changeset
+
+```bash
+pnpm changeset
+```
+
+### Versioning Packages (Local Testing)
+
+```bash
+# This updates package.json versions and CHANGELOGs
+pnpm run changeset:version
+```
+
+### Publishing Packages (Manual)
+
+```bash
+# Build and publish changed packages
+pnpm run changeset:publish
+```
+
+## Advanced Usage
+
+### Snapshot Releases
+
+For testing purposes, you can create snapshot releases:
+
+```bash
+pnpm changeset version --snapshot
+pnpm changeset publish --tag snapshot
+```
+
+### Prereleases
+
+To create prerelease versions:
+
+```bash
+# Enter prerelease mode
+pnpm changeset pre enter beta
+
+# Create changesets as usual
+pnpm changeset
+
+# Version and publish
+pnpm run changeset:version
+pnpm run changeset:publish
+
+# Exit prerelease mode
+pnpm changeset pre exit
+```
+
+## Configuration
+
+The changeset configuration is in `.changeset/config.json`:
+
+```json
+{
+  "baseBranch": "next",
+  "access": "public",
+  "ignore": ["@eggjs/monorepo", "helloworld-*", "site"]
+}
+```
+
+- `baseBranch`: The main branch for releases (set to `next`)
+- `access`: Package publish access level (set to `public`)
+- `ignore`: Packages that should never be published
+
+## Best Practices
+
+1. **Create changesets with your PR**: Always create a changeset when making changes that should be released
+2. **Write clear summaries**: The changeset summary becomes part of the changelog
+3. **Choose the correct bump type**: Follow semantic versioning principles
+4. **Review the Version PR**: Check the Version Packages PR before merging to ensure versions are correct
+5. **One changeset per feature**: Create separate changesets for different features or fixes
+
+## Comparison with Old Version Script
+
+### Old Method (scripts/version.js)
+
+- Bumped **all** package versions at once
+- Required manual execution
+- No automatic changelog generation
+- All-or-nothing release approach
+
+### New Method (Changesets)
+
+- Version **only changed** packages
+- Automatic PR creation
+- Automatic changelog generation
+- Selective package releases
+- Better tracking of what changed and why
+
+## Troubleshooting
+
+### No changeset detected
+
+If you forgot to create a changeset:
+
+```bash
+pnpm changeset
+```
+
+### Wrong version bump
+
+If you need to change a changeset:
+
+1. Delete the changeset file in `.changeset/`
+2. Create a new one with `pnpm changeset`
+
+### Failed publish
+
+Check the GitHub Actions logs for details. Common issues:
+
+- NPM authentication problems
+- Build failures
+- Network issues
+
+## Migration Notes
+
+The old version management scripts (`scripts/version.js`) are kept for backward compatibility and emergency use. However, **changesets should be the primary method** for version management going forward.
+
+To gradually migrate:
+
+1. Start using changesets for new changes
+2. Create changesets in all new PRs
+3. Let the automated workflow handle versioning and publishing
+4. Eventually deprecate the old scripts once the team is comfortable with changesets
+
+## References
+
+- [Changesets Documentation](https://github.com/changesets/changesets)
+- [Adding a Changeset](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md)
+- [Changesets CLI](https://github.com/changesets/changesets/blob/main/packages/cli/README.md)