name: 版本发布管理 description: 管理发布准备工作，包括验证、版本号更新、文档验证和安全检查。
版本发布管理
使用时机
- 准备新版本发布
- 版本号更新
- 发布前验证
- 发布前文档验证
发布工作流概览
| 阶段 | 目的 | 是否阻塞？ |
|---|---|---|
| 1. 发布前验证 | 测试、安全检查 | 是 |
| 2. 版本号更新 | 更新版本字符串 | 是 |
| 3. 文档验证 | 验证/更新文档 | 警告 |
| 4. 模板同步 | Cookiecutter对齐 | 警告 |
| 5. 构建验证 | 包构建 | 是 |
| 6. Git操作 | 提交和打标签 | 是 |
阶段1：发布前验证
1.1 验证迭代任务完成
# 检查未完成任务
bpsai-pair task list --status in_progress
bpsai-pair task list --status blocked
# 检查当前状态
bpsai-pair status
阻塞项：所有任务必须完成或移至下一个迭代。
1.2 运行完整测试套件
# 所有测试必须通过
pytest tests/ -v --tb=short
# 检查覆盖率是否达到目标（80%）
pytest tests/ --cov=bpsai_pair --cov-report=term-missing --cov-fail-under=80
阻塞项：如果测试失败，则无法继续发布。
1.3 安全扫描
# 扫描意外提交的密钥
bpsai-pair security scan-secrets
# 扫描依赖项中的已知漏洞
bpsai-pair security scan-deps
阻塞项：检测到密钥 = 无法发布。 警告：依赖项漏洞应进行审查，但可能不会阻塞发布。
阶段2：版本号更新
定位版本文件
grep -E "^version|__version__" tools/cli/pyproject.toml tools/cli/bpsai_pair/__init__.py
更新两个文件
| 文件 | 格式 |
|---|---|
pyproject.toml |
version = "X.Y.Z" |
__init__.py |
__version__ = "X.Y.Z" |
注意：文件中的版本号没有’v’前缀。Git标签使用’v’前缀。
需要更新的相关文件
| 文件 | 更新内容 |
|---|---|
capabilities.yaml |
version: "X.Y.Z" |
config.yaml |
version: "X.Y.Z" |
阶段3：文档验证
3.1 必需文档
# 检查CHANGELOG是否有此版本的条目
grep -A 20 "## \[X.Y.Z\]" CHANGELOG.md
# 检查README是否提及当前功能
head -100 README.md
# 检查FEATURE_MATRIX是否最新
head -50 .paircoder/docs/FEATURE_MATRIX.md
3.2 文档新鲜度
# 检查修改日期
git log -1 --format="%ci" -- README.md
git log -1 --format="%ci" -- CHANGELOG.md
git log -1 --format="%ci" -- .paircoder/docs/FEATURE_MATRIX.md
警告：如果任何必需文档超过7天未更新 - 可能需要更新。
3.3 CHANGELOG条目格式
如果缺失，请按照Keep a Changelog格式创建条目：
## [X.Y.Z] - YYYY-MM-DD
### 新增
- 功能1
- 功能2
### 变更
- 变更1
### 修复
- 修复1
### 移除
- （如适用）
从归档任务生成内容：
bpsai-pair task changelog-preview --since <last-version>
阶段4：模板同步（仅PairCoder）
验证cookiecutter模板与当前版本匹配：
# 检查模板是否存在
ls -la tools/cli/bpsai_pair/data/cookiecutter-paircoder/
# 比较关键文件
diff .paircoder/config.yaml \
tools/cli/bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/.paircoder/config.yaml
diff CLAUDE.md \
tools/cli/bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/CLAUDE.md
应保持同步的关键文件：
config.yaml结构（非值）CLAUDE.md说明capabilities.yaml格式- 技能文件
阶段5：构建验证
# 清理旧构建
rm -rf tools/cli/dist/ tools/cli/build/ tools/cli/*.egg-info
# 构建包
cd tools/cli && pip install build && python -m build
# 验证干净安装
pip install dist/*.whl --force-reinstall
# 验证版本是否正确
bpsai-pair --version
阶段6：发布检查清单
- [ ] 所有迭代任务完成
- [ ] 测试通过（100%）
- [ ] 覆盖率 ≥ 80%
- [ ] 代码库中没有密钥
- [ ] pyproject.toml中的版本号已更新
- [ ] init.py中的版本号已更新
- [ ] capabilities.yaml中的版本号已更新
- [ ] config.yaml中的版本号已更新
- [ ] CHANGELOG已更新
- [ ] README最新
- [ ] FEATURE_MATRIX已更新
- [ ] Cookiecutter模板已同步（如适用）
- [ ] 包构建成功
- [ ] 包安装干净
阶段7：Git操作
# 暂存所有更改
git add -A
# 提交发布消息
git commit -m "发布 vX.Y.Z"
# 创建带注释的标签
git tag -a "vX.Y.Z" -m "发布 vX.Y.Z"
# 显示将要推送的内容
git log --oneline -5
git tag -l | tail -5
暂时不要推送 - 让用户审查并确认。
阶段8：报告摘要
📦 **发布已准备就绪**：vX.Y.Z
**发布前检查**：
- ✅ 所有任务完成
- ✅ 测试：XXX通过
- ✅ 覆盖率：XX%
- ✅ 安全：干净
**文档**：
- ✅ CHANGELOG：已更新
- ✅ README：最新
- ✅ FEATURE_MATRIX：已更新
- ⚠️ 用户指南：X天前最后更新（建议审查）
**Cookiecutter**：
- ✅ 模板已同步
**构建**：
- ✅ 包已构建：bpsai_pair-X.Y.Z-py3-none-any.whl
- ✅ 安装干净
- ✅ 版本已验证
**准备发布**：
```bash
git push origin main
git push origin vX.Y.Z
然后发布到PyPI：
cd tools/cli && twine upload dist/*
## 错误恢复
### 测试失败
1. 不要继续发布
2. 修复失败的测试
3. 从阶段1重新运行
### 检测到密钥
1. 不要继续发布
2. 从历史记录中删除密钥（git filter-branch或BFG）
3. 轮换任何暴露的凭据
4. 重新运行安全扫描
### 文档过时
1. 警告，非阻塞项
2. 用户可以选择更新或继续
3. 记录决定
### Cookiecutter不同
1. 确定差异是否是有意的
2. 如果模板应该更新，请更新
3. 如果差异是项目特定的，请记录原因
## 配置参考
`config.yaml`中的发布配置：
```yaml
release:
version_source: tools/cli/pyproject.toml
documentation:
- CHANGELOG.md
- README.md
- .paircoder/docs/FEATURE_MATRIX.md
cookie_cutter:
template_path: tools/cli/bpsai_pair/data/cookiecutter-paircoder
sync_required: true
freshness_days: 7
版本格式参考
| 位置 | 格式 | 示例 |
|---|---|---|
| pyproject.toml | X.Y.Z | 2.9.0 |
| init.py | X.Y.Z | 2.9.0 |
| Git标签 | vX.Y.Z | v2.9.0 |
| CHANGELOG | [X.Y.Z] | [2.9.0] |