设计系统版本管理完全指南

版本管理的重要性

设计系统作为多项目共享的基础设施，版本管理尤为关键：

• 稳定性 - 业务项目可以锁定可靠版本
• 可追溯 - 了解每个版本的变化
• 渐进升级 - 控制升级节奏和风险
• 协作效率 - 团队共识和沟通基础

语义化版本规范

SemVer 基础

遵循 MAJOR.MINOR.PATCH 格式：

预发布版本

1.0.0-alpha.1   # 内部测试
1.0.0-beta.1    # 公开测试
1.0.0-rc.1      # 发布候选
1.0.0           # 正式发布

版本号决策

是否删除了组件或属性？
├── 是 → MAJOR
└── 否 → 是否修改了必填属性或类型？
         ├── 是 → MAJOR
         └── 否 → 是否新增了组件或功能？
                  ├── 是 → MINOR
                  └── 否 → PATCH

变更日志管理

Changelog 格式

# Changelog

## [2.3.0] - 2024-12-31

### Added
- 新增 `DatePicker` 日期选择器组件
- `Button` 组件新增 `icon` 插槽

### Changed
- `Modal` 组件默认动画时长从 300ms 调整为 200ms

### Deprecated
- `Input` 组件的 `clearable` 属性将在 3.0 移除，请使用 `allowClear`

### Fixed
- 修复 `Select` 组件在 Safari 下的样式问题 (#123)
- 修复 `Table` 分页器点击无效的问题 (#145)

## [2.2.1] - 2024-12-20

### Fixed
- 修复 `Tooltip` 组件定位偏移问题

自动生成变更日志

使用 Conventional Commits 规范：

# 提交格式
<type>(<scope>): <description>

# 示例
feat(Button): add icon slot support
fix(Select): fix Safari styling issue
docs(Modal): update API documentation
BREAKING CHANGE: remove deprecated `clearable` prop

// package.json
{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
  }
}

兼容性处理

废弃流程

// 1. 标记废弃
/**
 * @deprecated 请使用 allowClear 代替，将在 3.0 移除
 */
interface InputProps {
  clearable?: boolean
  allowClear?: boolean
}

// 2. 运行时警告
const Input = (props) => {
  if (props.clearable !== undefined) {
    console.warn(
      '[DesignSystem] Input: clearable 属性已废弃，' +
      '请使用 allowClear 代替，将在 3.0 版本移除'
    )
  }
  
  const shouldClear = props.allowClear ?? props.clearable
  // ...
}

// 3. 文档标记

迁移指南

# 从 v2 升级到 v3

## 破坏性变更

### Button 组件

**变更**：`type` 属性重命名为 `variant`

```diff
- <Button type="primary">提交</Button>
+ <Button variant="primary">提交</Button>

迁移脚本：

npx @design-system/codemod button-type-to-variant ./src

Input 组件

变更：移除 clearable 属性

- <Input clearable />
+ <Input allowClear />

### Codemod 自动迁移

```javascript
// codemods/button-type-to-variant.js
module.exports = function transformer(file, api) {
  const j = api.jscodeshift
  const root = j(file.source)
  
  // 找到所有 Button 组件
  root
    .find(j.JSXElement, {
      openingElement: { name: { name: 'Button' } }
    })
    .forEach(path => {
      const attrs = path.node.openingElement.attributes
      
      attrs.forEach(attr => {
        if (attr.name && attr.name.name === 'type') {
          attr.name.name = 'variant'
        }
      })
    })
  
  return root.toSource()
}

发布流程

自动化发布

# .github/workflows/release.yml
name: Release

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org/
      
      - run: npm ci
      - run: npm test
      - run: npm run build
      
      # 自动版本号和发布
      - name: Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: npx semantic-release

发布检查清单

## 发布前检查

- [ ] 所有测试通过
- [ ] 文档已更新
- [ ] CHANGELOG 已更新
- [ ] 版本号正确
- [ ] 破坏性变更已标记
- [ ] 迁移指南已准备（如需要）

## 发布后验证

- [ ] npm 包可正常安装
- [ ] 文档站已更新
- [ ] 通知相关团队

多版本支持

长期支持策略

分支管理

main        → 最新开发版
release/3.x → 当前稳定版
release/2.x → LTS 版本
release/1.x → 仅关键安全修复

回溯修复

# Cherry-pick 修复到旧版本
git checkout release/2.x
git cherry-pick <commit-hash>
git push origin release/2.x

# 从 2.x 分支发布
npm version patch
npm publish --tag v2-lts

版本依赖管理

Peer Dependencies

{
  "peerDependencies": {
    "vue": "^3.3.0",
    "tailwindcss": "^3.0.0"
  },
  "peerDependenciesMeta": {
    "tailwindcss": {
      "optional": true
    }
  }
}

锁定依赖范围

{
  "dependencies": {
    "@floating-ui/vue": "^1.0.0",
    "dayjs": "^1.11.0"
  },
  "devDependencies": {
    "vue": "3.3.8"
  }
}

版本沟通

发布公告模板

# 🎉 Design System v2.5.0 发布

## 新功能

### DateRangePicker 日期范围选择器
支持选择日期范围，适用于报表筛选等场景。

```vue
<DateRangePicker v-model="dateRange" />

Button 新增 loading 状态

点击后自动显示加载状态，防止重复提交。

升级指南

npm install @company/design-system@2.5.0

完整变更日志

查看 CHANGELOG.md

### 废弃通知

```markdown
# ⚠️ 废弃通知

## Input.clearable 属性

`clearable` 属性将在 v3.0 移除。

**迁移方法**：
```diff
- <Input clearable />
+ <Input allowClear />

废弃时间线：

• v2.5: 添加废弃警告
• v2.8: 开发环境警告
• v3.0: 移除属性

## 最佳实践

| 原则 | 说明 |
|-----|------|
| 避免破坏性变更 | 优先向后兼容方案 |
| 渐进式废弃 | 给用户迁移时间 |
| 清晰的文档 | 变更日志 + 迁移指南 |
| 自动化流程 | CI/CD 自动发布 |
| 及时沟通 | 通知依赖项目 |

## 总结

设计系统版本管理的核心在于：

1. **规范版本号** - 遵循语义化版本
2. **记录变更** - 完整的变更日志
3. **平滑迁移** - 废弃流程 + 迁移工具
4. **自动化** - CI/CD 发布流程
5. **有效沟通** - 及时通知和文档

良好的版本管理让设计系统既保持创新又确保稳定。