# 发布检查清单

使用本清单确保每次发布都遵循最佳实践。

## 📋 发布前检查

### 1. 代码质量
- [ ] 所有测试通过 (`uv run pytest`)
- [ ] 代码覆盖率 ≥ 80% (`uv run pytest --cov=agentcenter --cov-fail-under=80`)
- [ ] 代码已格式化 (`uv run black src/ tests/`)
- [ ] Ruff 检查通过 (`uv run ruff check src/ tests/`)
- [ ] 类型检查通过 (`uv run mypy src/`)

### 2. 文档
- [ ] README.md 更新
- [ ] CHANGELOG.md 已更新本版本内容
- [ ] 文档中的示例代码可运行
- [ ] API 文档准确

### 3. 版本管理
- [ ] 版本号已更新（遵循语义化版本）
- [ ] Git 工作目录干净（已提交所有更改）
- [ ] pyproject.toml 中版本号正确

### 4. 配置检查
- [ ] pyproject.toml 中的作者信息正确
- [ ] LICENSE 文件存在
- [ ] .gitignore 不包含敏感信息
- [ ] dependencies 列表完整且版本号合理

### 5. 安全检查
- [ ] 没有硬编码的密钥或凭证
- [ ] .env 文件未被包含
- [ ] API tokens 安全存储

## 🚀 发布步骤

### 自动化发布（推荐）

```bash
# 使用发布脚本
./scripts/release.sh [新版本号]
```

### 手动发布

```bash
# 1. 更新版本号（编辑 pyproject.toml）

# 2. 更新 CHANGELOG.md

# 3. 运行测试
uv run pytest --cov=agentcenter --cov-fail-under=80

# 4. 代码质量检查
uv run black src/ tests/
uv run ruff check src/ tests/ --fix
uv run mypy src/

# 5. 提交更改
git add .
git commit -m "Release version X.Y.Z"
git push origin main

# 6. 创建标签
git tag -a vX.Y.Z -m "Release version X.Y.Z"
git push origin vX.Y.Z

# 7. 构建包
rm -rf dist/
uv build

# 8. 上传到 TestPyPI（可选）
uv run twine upload --repository testpypi dist/*

# 9. 测试 TestPyPI 包
pip install --index-url https://test.pypi.org/simple/ agentcenter==X.Y.Z

# 10. 上传到 PyPI
uv run twine upload dist/*
```

## ✅ 发布后检查

- [ ] PyPI 页面显示正常 (https://pypi.org/project/agentcenter/)
- [ ] 可以使用 pip 安装 (`pip install agentcenter`)
- [ ] 可以使用 uv 安装 (`uv add agentcenter`)
- [ ] 安装后导入正常 (`python -c "from agentcenter import AgentCenter"`)
- [ ] CLI 命令可用 (`agentcenter --help`)
- [ ] GitHub Release 已创建（如果适用）
- [ ] 文档链接有效

## 🔄 回滚计划

如果发布后发现问题：

1. **轻微问题**: 发布补丁版本 (X.Y.Z -> X.Y.Z+1)
2. **严重问题**:
   - 在 PyPI 上 yank 该版本
   - 立即发布修复版本
   - 更新文档说明

## 📝 版本号规则

遵循语义化版本 (SemVer):

- **MAJOR** (X.0.0): 不兼容的 API 变更
- **MINOR** (0.X.0): 向后兼容的功能新增
- **PATCH** (0.0.X): 向后兼容的问题修正

### 示例

- `0.1.0` → `0.1.1`: Bug 修复
- `0.1.1` → `0.2.0`: 新功能（兼容）
- `0.2.0` → `1.0.0`: 第一个稳定版本
- `1.0.0` → `2.0.0`: 破坏性更新

## 🏷️ 预发布版本

- **Alpha**: `0.2.0a1`, `0.2.0a2`
- **Beta**: `0.2.0b1`, `0.2.0b2`
- **RC**: `0.2.0rc1`, `0.2.0rc2`

## 📞 需要帮助？

查看完整文档：`docs/publishing.md`

## ⚠️ 重要提醒

- **PyPI 发布是永久的**，无法删除
- 发布前务必在 TestPyPI 测试
- 版本号一旦发布就不能重用
- 包名称全局唯一，发布前确认名称可用

---

**最后检查**: 在勾选所有项目后，才进行发布！
