标准答案
- 遵守 SemVer，用 major 承载破坏性变更，用 minor 增加兼容能力，用 patch 修复问题。
- 废弃 API 先标记 deprecated，给出替代写法和移除时间。
- 迁移指南要包含影响范围、示例代码、常见错误和回滚建议。
- 组件库要测试宿主框架、构建工具、主题、样式和类型声明兼容。
- 发布记录要说明 breaking changes、依赖变化和已知风险。
题目解析
组件库影响的是多个项目，不能像业务代码一样随意改 API。一个 props 改名、样式变量删除或 peerDependencies 范围变化，都可能让使用方批量受影响。
好的废弃流程是渐进式的：先保留兼容并告警，再提供迁移路径，最后在 major 版本删除。
迁移指南要面向使用者，而不是维护者。使用者需要知道自己该搜哪些 API、怎么改、怎么验证。
常见误区
- minor 版本删除 API，导致使用方无预期破坏。
- 只写“升级组件库”，没有列出具体迁移项。
- 组件库没有覆盖类型声明、样式变量和 peer 依赖兼容测试。