# 发布指南

本文档说明如何发布 NSFC Spider 新版本。

## 发布前检查清单

- [ ] 所有测试通过
- [ ] 文档已更新
- [ ] CHANGELOG.md 已更新
- [ ] 版本号已更新
- [ ] 代码已合并到主分支

## 版本号规范

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

- **主版本号**：不兼容的 API 修改
- **次版本号**：向下兼容的功能性新增
- **修订号**：向下兼容的问题修正

示例：`1.2.3`
- 1 = 主版本
- 2 = 次版本
- 3 = 修订版本

## 发布步骤

### 方式一：使用发布脚本（推荐）

```bash
python scripts/release.py
```

脚本会自动：
1. 运行测试
2. 清理旧构建
3. 构建新包
4. 检查包质量
5. 上传到 PyPI

### 方式二：手动发布

#### 1. 更新版本号

编辑以下文件：

**pyproject.toml**
```toml
[project]
version = "0.2.0"
```

**src/nsfc_spider/__init__.py**
```python
__version__ = "0.2.0"
```

#### 2. 更新 CHANGELOG.md

```markdown
## [0.2.0] - 2026-02-15

### 新增
- 添加新功能描述

### 修复
- 修复的问题描述
```

#### 3. 提交更改

```bash
git add .
git commit -m "chore: bump version to 0.2.0"
git push
```

#### 4. 创建标签

```bash
git tag -a v0.2.0 -m "Release version 0.2.0"
git push origin v0.2.0
```

#### 5. 构建包

```bash
# 清理旧构建
rm -rf dist/ build/ *.egg-info

# 构建
python -m build
```

#### 6. 检查包

```bash
twine check dist/*
```

#### 7. 上传到 TestPyPI（可选）

```bash
twine upload --repository testpypi dist/*
```

测试安装：
```bash
pip install --index-url https://test.pypi.org/simple/ nsfc-spider
```

#### 8. 上传到 PyPI

```bash
twine upload dist/*
```

#### 9. 创建 GitHub Release

1. 访问 GitHub 仓库的 Releases 页面
2. 点击 "Draft a new release"
3. 选择刚创建的标签
4. 填写发布说明（从 CHANGELOG.md 复制）
5. 发布

## 自动化发布（GitHub Actions）

项目已配置 GitHub Actions，当创建新 Release 时自动发布到 PyPI。

### 配置步骤

1. 在 PyPI 创建 API Token
2. 在 GitHub 仓库设置中添加 Secret：
   - Name: `PYPI_API_TOKEN`
   - Value: 你的 PyPI Token

3. 创建 Release 时自动触发发布

## 发布后

1. 验证安装：
   ```bash
   pip install --upgrade nsfc-spider
   nsfc-spider --version
   ```

2. 更新文档网站（如果有）

3. 发布公告：
   - GitHub Discussions
   - 社交媒体
   - 邮件列表

## 回滚

如果发现严重问题需要回滚：

```bash
# 删除 PyPI 上的版本（不推荐，只能删除一次）
# 联系 PyPI 支持

# 发布修复版本
# 例如：0.2.0 有问题，发布 0.2.1 修复
```

## 常见问题

### 1. 上传失败：版本已存在

PyPI 不允许重复上传相同版本号。解决方法：
- 增加版本号重新发布
- 使用 TestPyPI 测试

### 2. 包大小过大

检查是否包含了不必要的文件：
- 查看 MANIFEST.in
- 使用 `.gitignore` 排除

### 3. 依赖冲突

确保 `pyproject.toml` 中的依赖版本范围合理。

## 参考资源

- [Python 打包指南](https://packaging.python.org/)
- [Twine 文档](https://twine.readthedocs.io/)
- [语义化版本](https://semver.org/lang/zh-CN/)
