Back to Details

breaking-changes-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Breaking Changes Management

破坏性变更管理

Skill Paths

技能路径

  • Workspace skills: 
    .github/skills/
  • Global skills: 
    C:/Users/LOQ/.agents/skills/
  • 工作区技能：
    .github/skills/
  • 全局技能：
    C:/Users/LOQ/.agents/skills/

Activation Conditions

激活条件

Use this skill when:
  • Introducing breaking API changes
  • Creating migration guides
  • Deprecating features with timeline
  • Updating CHANGELOG.md for major versions
  • Managing version transitions
在以下场景使用本技能：
  • 引入破坏性API变更
  • 创建迁移指南
  • 带有时间线的功能弃用
  • 为主版本更新CHANGELOG.md
  • 管理版本过渡

Breaking Change Documentation

破坏性变更文档

When breaking API changes occur:
  • Document what changed
  • Provide before/after examples
  • Include step-by-step migration instructions
  • Update CHANGELOG.md with BREAKING prefix
当发生破坏性API变更时：
  • 记录变更内容
  • 提供变更前后示例
  • 包含分步迁移说明
  • 在CHANGELOG.md中添加BREAKING前缀进行更新

Deprecation Process

弃用流程

See Deprecation Procedures for:
  • marking deprecated features
  • suggesting alternative approaches
  • creating migration guides
  • updating changelog with deprecation notice
  • setting timeline for removal
请参阅弃用流程了解：
  • 标记已弃用功能
  • 推荐替代方案
  • 创建迁移指南
  • 在变更日志中添加弃用通知
  • 设置移除时间线

Migration Guides

迁移指南

Create migration guides when:
  1. Breaking API changes occur: Document what changed, provide before/after examples, include step-by-step migration instructions
  2. Major version updates: List all breaking changes, provide upgrade checklist, include common migration issues and solutions
  3. Deprecating features: Mark deprecated features clearly, suggest alternative approaches, include timeline for removal
在以下场景创建迁移指南：
  1. 发生破坏性API变更时：记录变更内容，提供变更前后示例，包含分步迁移说明
  2. 主版本更新时：列出所有破坏性变更，提供升级检查清单，包含常见迁移问题及解决方案
  3. 弃用功能时：清晰标记已弃用功能，推荐替代方案，包含移除时间线

Changelog Format

变更日志格式

markdown
undefined
markdown
undefined

[Version] - YYYY-MM-DD

[Version] - YYYY-MM-DD

Added

Added

  • New feature description with reference to PR/issue
  • New feature description with reference to PR/issue

Changed

Changed

  • BREAKING: Description of breaking change
  • Other changes
  • BREAKING: Description of breaking change
  • Other changes

Fixed

Fixed

  • Bug fix description
undefined
  • Bug fix description
undefined

Review Checklist

审核清单

  • Breaking changes clearly documented
  • Migration guide created if needed
  • Deprecated features marked with alternative suggestions
  • Removal timeline specified
  • ChangeLog updated with BREAKING prefix
  • Before/after examples provided
  • 破坏性变更已清晰记录
  • 已按需创建迁移指南
  • 已标记已弃用功能并提供替代建议
  • 已指定移除时间线
  • 已使用BREAKING前缀更新ChangeLog
  • 已提供变更前后示例