# 版本发布指南

本指南说明如何按照 Python 包版本管理最佳实践发布新版本。

## 发布流程

### 第一步：准备发布

1. **确保代码已提交且测试通过**

```bash
# 检查工作区状态
git status

# 运行所有测试
uv run pytest --cov=src

# 运行代码质量检查
uv run black src/ tests/
uv run ruff check src/ tests/ --fix
uv run mypy src/
```

2. **检查当前版本**

```bash
# 查看最近的标签
git tag -l -n 5

# 检查距离上一个发布有多少个提交
git log --oneline v1.0.0..HEAD  # 替换 v1.0.0 为最新标签
```

### 第二步：创建发布标签

```bash
# 1. 确保所有更改已提交
git add .
git commit -m "feat: 功能描述"

# 2. 创建语义化版本标签
# 版本格式: v主版本.次版本.修订版本
# 例如: v1.0.0, v1.1.0, v1.0.1
git tag v1.0.0

# 3. 推送代码和标签到远程
git push origin main
git push origin v1.0.0
```

## 版本号规则

遵循 [语义化版本](https://semver.org/lang/zh-CN/) 规范：

- **主版本号**：有重大 API 变更时增加
- **次版本号**：添加新功能（向下兼容）时增加
- **修订版本号**：修复 BUG 时增加

### 示例

| 场景 | 版本号 |
|------|--------|
| 初始发布 | v1.0.0 |
| 添加新功能 | v1.1.0 |
| 修复 BUG | v1.0.1 |
| 重大变更 | v2.0.0 |

## 版本发布后

### 自动化流程

1. **GitHub Actions 自动触发**
   - 检测到新标签推送时，自动触发 `.github/workflows/publish.yml`
   - 自动构建包并发布到 PyPI
   - 自动创建 GitHub Release

2. **验证发布成功**

```bash
# 在 PyPI 上查看包
# https://pypi.org/project/satellitecenter/

# 验证包版本
pip install --upgrade satellitecenter
python -c "import satellitecenter; print(satellitecenter.__version__)"
# 应该输出: 1.0.0
```

## 开发环境版本验证

### 本地验证

```bash
# 1. 检查 setuptools_scm 识别的版本
python -c "from setuptools_scm import get_version; print(get_version())"

# 2. 检查包导入的版本
python -c "import satellitecenter; print(satellitecenter.__version__)"

# 3. 查看生成的 _version.py
cat src/satellitecenter/_version.py
```

### 输出示例

```
# setuptools_scm 识别的版本
1.0.0

# 包导入的版本
1.0.0

# _version.py 内容
# Generated by setuptools_scm
__version__ = '1.0.0'
__version_tuple__ = (1, 0, 0)
```

## 常见问题

### Q1：如何修正错误的标签？

```bash
# 如果标签打错了，可以删除并重新创建
git tag -d v1.0.0              # 删除本地标签
git push origin :refs/tags/v1.0.0  # 删除远程标签

# 然后重新创建正确的标签
git tag v1.0.1
git push origin v1.0.1
```

### Q2：如何发布 RC（发布候选）版本？

```bash
# RC 版本格式: v1.0.0rc1, v1.0.0rc2 等
git tag v1.0.0rc1
git push origin v1.0.0rc1
```

### Q3：为什么 CI 构建失败？

常见原因和解决方案：

| 原因 | 解决 |
|------|------|
| 缺少 PYPI_API_TOKEN | 在 GitHub Secrets 中添加 PyPI token |
| Git 历史不完整 | GitHub Actions 中已配置 `fetch-depth: 0` |
| 多个标签在同一提交 | 删除不需要的标签，保留一个发布标签 |

### Q4：版本号不一致怎么办？

如果安装后的包版本与标签不符，检查：

1. **CI 日志** - 查看构建时识别的版本
2. **PyPI 页面** - 确认上传的版本
3. **清理缓存** - `pip install --upgrade --no-cache-dir satellitecenter`

## 版本历史示例

```
v0.1.0   - 初始版本发布
v0.1.1   - 修复日志记录 BUG
v0.2.0   - 添加管道输入支持
v1.0.0   - 完整的版本管理功能
v1.0.1   - 修复 UTF-8 BOM 处理
v1.1.0   - 添加内存日志缓冲
```

## 检查清单

发布前确认以下项目：

- [ ] 所有测试通过（`uv run pytest`）
- [ ] 代码符合风格要求（`uv run black src/` `uv run ruff check src/`）
- [ ] 类型检查通过（`uv run mypy src/`）
- [ ] README 和文档已更新
- [ ] CHANGELOG 已更新
- [ ] 没有提交未跟踪的重要文件
- [ ] Git 工作区干净（`git status` 显示 working tree clean）
- [ ] 标签格式正确（`vX.Y.Z`）

## 参考资源

- [语义化版本](https://semver.org/lang/zh-CN/)
- [setuptools_scm 文档](https://setuptools-scm.readthedocs.io/)
- [PyPI 发布指南](https://packaging.python.org/tutorials/packaging-projects/)
- [GitHub Actions 文档](https://docs.github.com/zh/actions)

---

**特别提示**：使用 git 标签作为版本号来源，避免手动维护版本号，这样可以确保开发、构建、安装环节版本号始终一致！
