Nigel
/
mcp-swagger-server
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
mcp-swagger-server/docs/changesets-implementation-g...

9.2 KiB
Raw Blame History

MCP Swagger Server - Changesets 实施指南

项目概述

本项目是一个基于 pnpm workspace 的 monorepo 架构，包含以下可发布的包：

  • mcp-swagger-server - 主服务包 (v1.0.9)
  • mcp-swagger-parser - 解析器包 (v1.0.5)
  • @mcp-swagger/api - API 服务包 (私有，不发布)

当前状态分析

现有配置

  • 包管理器: pnpm (workspace 模式)
  • TypeScript: 项目引用 (composite 模式)
  • 发布方式: 手动 pnpm pack 命令
  • 版本管理: 手动更新版本号

问题识别

  1. 版本管理繁琐，容易出错
  2. 缺乏自动化的 CHANGELOG 生成
  3. 多包发布缺乏协调机制
  4. 发布流程不规范

Changesets 集成方案

第一步：安装依赖

# 安装 Changesets
pnpm add -D @changesets/cli @changesets/changelog-github

# 初始化 Changesets
pnpm changeset init

第二步：配置文件

1. .changeset/config.json

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/changelog-github",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": ["@mcp-swagger/api"],
  "privatePackages": {
    "version": true,
    "tag": false
  }
}

配置说明：

  • changelog: 使用 GitHub 风格的 changelog
  • ignore: 忽略私有的 API 包
  • access: 公开发布
  • updateInternalDependencies: 内部依赖更新策略

2. 根目录 package.json 脚本更新

{
  "scripts": {
    "build": "node scripts/build.js",
    "build:packages": "node scripts/build.js --non-ui",
    "prepack": "node scripts/build.js",
    "pack": "pnpm build && changeset publish --dry-run",
    "changeset": "changeset",
    "changeset:version": "changeset version",
    "changeset:publish": "changeset publish",
    "changeset:status": "changeset status",
    "version-packages": "changeset version && pnpm install --lockfile-only",
    "release": "pnpm build && changeset publish",
    "release:dry": "pnpm build && changeset publish --dry-run"
  }
}

第三步：.pnpmrc 文件需求分析

是否需要 .pnpmrc 文件？

根据你的项目情况，建议创建 .pnpmrc 文件，原因如下：

  1. 发布配置统一管理
  2. workspace 行为优化
  3. 依赖提升控制
  4. 构建性能优化

推荐的 .pnpmrc 配置

# 启用 workspace 协议
prefer-workspace-packages=true

# 避免依赖提升问题
hoist-pattern[]=*eslint*
hoist-pattern[]=*prettier*
hoist-pattern[]=*typescript*

# 发布配置
publish-branch=main
access=public

# 性能优化
store-dir=~/.pnpm-store
verify-store-integrity=true

# 严格模式
strict-peer-dependencies=false
auto-install-peers=true

# 构建缓存
enable-pre-post-scripts=true

第四步：包配置优化

mcp-swagger-server/package.json

{
  "name": "mcp-swagger-server",
  "version": "1.0.9",
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org/"
  },
  "files": [
    "dist/**/*",
    "README.md",
    "CHANGELOG.md",
    "LICENSE"
  ]
}

mcp-swagger-parser/package.json

{
  "name": "mcp-swagger-parser", 
  "version": "1.0.5",
  "publishConfig": {
    "access": "public",
    "registry": "https://registry.npmjs.org/"
  },
  "files": [
    "dist/**/*",
    "README.md", 
    "CHANGELOG.md",
    "LICENSE"
  ]
}

第五步：工作流程

开发者工作流

  1. 开发功能

    git checkout -b feature/new-feature
# 开发代码...

  2. 创建变更集

    pnpm changeset

    选择选项：

    • 选择要更新的包: mcp-swagger-server, mcp-swagger-parser
    • 选择版本类型: patch, minor, major
    • 输入描述: "Add new feature for XXX"

  3. 提交代码

    git add .
git commit -m "feat: add new feature"
git push origin feature/new-feature

维护者发布流程

  1. 更新版本

    pnpm changeset version

  2. 安装依赖

    pnpm install

  3. 构建项目

    pnpm build

  4. 发布包

    # 试运行（推荐）
pnpm release:dry

# 正式发布
pnpm release

GitHub Actions 集成

.github/workflows/release.yml

name: Release

on:
  push:
    branches:
      - main

concurrency: ${{ github.workflow }}-${{ github.ref }}

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Setup pnpm
        uses: pnpm/action-setup@v3
        with:
          version: 8
          run_install: false

      - name: Get pnpm store directory
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV          

      - name: Setup pnpm cache
        uses: actions/cache@v3
        with:
          path: ${{ env.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-            

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build packages
        run: pnpm build

      - name: Create Release Pull Request or Publish to npm
        id: changesets
        uses: changesets/action@v1
        with:
          publish: pnpm release
          commit: "chore: release packages"
          title: "chore: release packages"
          createGithubReleases: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/changeset-check.yml

name: Changeset Check

on:
  pull_request:
    branches:
      - main

jobs:
  changeset-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Setup pnpm
        uses: pnpm/action-setup@v3
        with:
          version: 8
          run_install: false

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Check for changeset
        run: |
          if [ -z "$(pnpm changeset status --output=json | jq -r '.releases[] | select(.name != "@mcp-swagger/api")')" ]; then
            echo "::error::No changeset found. Please run 'pnpm changeset' to create one."
            exit 1
          fi

实施步骤

准备阶段

  1. 创建 .pnpmrc 文件
  2. 安装 Changesets 依赖
  3. 初始化配置文件
  4. 更新 package.json 脚本

测试阶段

  1. 创建测试分支
  2. 模拟变更集创建
  3. 验证版本更新
  4. 测试发布流程

部署阶段

  1. 配置 GitHub Actions
  2. 设置 NPM_TOKEN
  3. 正式启用流程
  4. 团队培训

迁移脚本

#!/bin/bash
# migration.sh - Changesets 迁移脚本

echo "🚀 开始 Changesets 迁移..."

# 1. 创建 .pnpmrc 文件
echo "📝 创建 .pnpmrc 文件..."
cat > .pnpmrc << 'EOF'
prefer-workspace-packages=true
hoist-pattern[]=*eslint*
hoist-pattern[]=*prettier*
hoist-pattern[]=*typescript*
publish-branch=main
access=public
store-dir=~/.pnpm-store
verify-store-integrity=true
strict-peer-dependencies=false
auto-install-peers=true
enable-pre-post-scripts=true
EOF

# 2. 安装 Changesets
echo "📦 安装 Changesets..."
pnpm add -D @changesets/cli @changesets/changelog-github

# 3. 初始化 Changesets
echo "⚙️ 初始化 Changesets..."
pnpm changeset init

# 4. 创建 GitHub Actions 目录
echo "🔄 创建 GitHub Actions..."
mkdir -p .github/workflows

echo "✅ 迁移完成！请手动完成以下步骤："
echo "1. 更新 package.json 脚本"
echo "2. 配置 .changeset/config.json"
echo "3. 创建 GitHub Actions 工作流"
echo "4. 设置 NPM_TOKEN 密钥"

最佳实践

变更集编写规范

# 好的变更集示例

---
"mcp-swagger-server": minor
"mcp-swagger-parser": patch
---

Add support for OpenAPI 3.1 specifications

This change adds full support for OpenAPI 3.1 specifications including:
- New schema validation rules
- Enhanced error reporting
- Better type inference

Breaking changes: None

版本发布策略

  • patch: bug 修复，安全补丁
  • minor: 新功能，向后兼容
  • major: 破坏性变更，API 变更

发布检查清单

  • 所有测试通过
  • 文档已更新
  • CHANGELOG 生成正确
  • 版本号符合语义化版本规范
  • 依赖关系正确更新

常见问题

Q: 如何处理内部依赖？

A: Changesets 会自动处理内部依赖更新，配置 updateInternalDependencies: "patch" 即可。

Q: 如何跳过某些包的发布？

A: 在 config.json 中配置 ignore 数组。

Q: 如何处理预发布版本？

A: 使用 pnpm changeset pre enter alpha 进入预发布模式。

总结

通过集成 Changesets，你的项目将获得：

  • 自动化的版本管理
  • 规范化的发布流程
  • 完整的变更记录
  • 更好的团队协作

建议按照上述步骤逐步实施，确保每个环节都经过充分测试。