跳转至

版本管理预防策略

本文档定义版本号不一致和身份信息冲突的预防措施。

问题 1: 版本号不一致

问题描述

当前仓库由 release automation 管理版本和发布元数据。常规开发不再手动同步多个版本字段；重点是确保 release metadata 没有漂移。

文件 字段 说明
plugins/.../plugin.json version 插件本身版本
.github/.release-please-manifest.json component versions release-please 的组件版本来源
.claude-plugin/marketplace.json / .cursor-plugin/marketplace.json marketplace metadata 发布展示信息
plugin manifests description / capabilities 插件展示和安装元数据

风险

  • Marketplace 无法检测到更新（版本号相同或更低）
  • 用户看到不一致的版本信息，产生困惑
  • 组件数量过时，误导用户

预防措施

措施 1: 使用 release metadata 自动同步（推荐）

bun run release:sync-metadata
bun run release:validate

脚本会自动： 1. 根据 release-please manifest 和当前组件数量同步发布元数据 2. 更新 Claude / Cursor marketplace 相关描述 3. 验证 release 配置和元数据没有漂移

措施 2: 安装 pre-commit hook

# 安装 hook
cp scripts/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit  # macOS/Linux

# Windows 下需要确保 Git Bash 可执行

hook 会在提交时检查版本一致性，不一致则阻止提交。

措施 3: 手动检查（备选）

提交前运行验证脚本：

# Windows
powershell -ExecutionPolicy Bypass -File scripts/check-versions.ps1

# macOS/Linux
bash scripts/check-versions.sh

发版检查清单

每次发版必须完成：

  • [ ] release metadata 同步 - 运行 bun run release:sync-metadata
  • [ ] release metadata 验证 - 运行 bun run release:validate
  • [ ] CHANGELOG/Release Notes - 由 release automation 生成，不在普通 PR 中手写
  • [ ] 组件数量核对 - 如有新增/删除，更新以下位置：
  • CLAUDE.md 当前组件统计表
  • marketplace.json 插件描述
  • plugin.json 描述字段
  • [ ] 运行验证脚本 - 确认所有检查通过
  • [ ] 测试安装 - 在新环境测试 Marketplace 安装

问题 2: Fork 仓库身份信息冲突

问题描述

从上游 fork 后，以下信息仍指向原仓库：

  • marketplace.json 的 owner 信息
  • plugin.json 的 author/homepage/repository
  • CLAUDE.md 中的安装命令

风险

  • Claude Code 无法正确识别当前 fork
  • 安装指向错误的仓库
  • 上游同步时产生合并冲突

预防措施

措施 1: Fork 后立即初始化

参考 Fork 仓库初始化清单，在 fork 后第一时间完成身份信息修改。

措施 2: 上游同步时保护身份信息

同步上游更新时，使用以下策略：

# 1. 获取上游更新
git fetch upstream

# 2. 查看冲突文件
git diff upstream/main -- .claude-plugin/marketplace.json
git diff upstream/main -- plugins/compound-engineering/.claude-plugin/plugin.json

# 3. 合并时保留本地身份信息
git merge upstream/main --no-commit

# 4. 如果身份信息被覆盖，恢复本地版本
git checkout --ours .claude-plugin/marketplace.json
git checkout --ours plugins/compound-engineering/.claude-plugin/plugin.json

# 5. 手动合并其他内容（如版本号需要更新）
# 编辑文件，保留你的身份信息，使用上游的新功能

# 6. 完成合并
git add .
git commit -m "Sync upstream changes, preserve local identity"

措施 3: 使用 .gitattributes 保护文件（高级）

在仓库根目录创建 .gitattributes：

# 合并时优先使用本地版本（谨慎使用）
# .claude-plugin/marketplace.json merge=ours
# plugins/compound-engineering/.claude-plugin/plugin.json merge=ours

注意：此方法会完全忽略上游对这些文件的更改，可能错过重要更新。

自动化工具清单

脚本 用途 使用方式
bun run release:sync-metadata 同步 release metadata 修改插件清单后运行
bun run release:validate 验证 release 配置与元数据 提交前运行
scripts/check-versions.ps1 轻量身份和版本格式检查 提交前可选
scripts/check-versions.sh 轻量身份和版本格式检查 (Bash) 提交前可选
scripts/bump-version.ps1 旧版手工版本工具 一般不推荐
scripts/pre-commit Git hook 安装到 .git/hooks/

最佳实践总结

日常开发

  1. 不手动 bump release-owned 版本
  2. 修改插件清单、描述或组件数量后运行 bun run release:sync-metadata
  3. 提交前运行 bun run release:validate

上游同步

  1. 同步前备份身份信息相关文件
  2. 合并后检查身份信息是否被覆盖
  3. 运行 bun run release:sync-metadata
  4. 运行 bun run release:validate

新人入职/Fork 初始化

  1. Fork 后第一时间按 FORK-SETUP.md 初始化
  2. 安装 pre-commit hook
  3. 测试一次 bun run release:validate

相关文档