# UVM 发布指南

## 发布前准备

### 1. 环境检查
确保你已经：
- 安装了 [`uv`](https://github.com/astral-sh/uv)
- 准备了 PyPI 账户和 API token
- 配置了合适的 Python 版本 (>=3.9)

### 2. 代码质量检查
```bash
# 运行代码检查
uv run ruff check --fix .
uv run ruff format .

# 运行类型检查
uv run mypy uvm/

# 运行测试
uv run pytest tests/ --cov=uvm --cov-report=html
```

### 3. 版本号更新
在 `pyproject.toml` 中更新版本号：
```toml
[project]
name = "uvm"
version = "0.1.0"  # 更新为新的版本号
```

## 构建分发包

### 1. 安装构建工具
```bash
uv pip install build
```

### 2. 构建包
```bash
uv run python -m build
```

成功构建后会在 `dist/` 目录下生成：
- `uvm-0.1.0-py3-none-any.whl` (wheel 包)
- `uvm-0.1.0.tar.gz` (源码包)

### 3. 检查包内容
```bash
# 检查 wheel 包
python3 -m zipfile -l dist/uvm-0.1.0-py3-none-any.whl

# 检查源码包
tar -tzf dist/uvm-0.1.0.tar.gz | head -20
```

## 发布到 PyPI

### 1. 安装发布工具
```bash
uv pip install twine
```

### 2. 测试发布 (可选但推荐)
首先发布到 TestPyPI 进行测试：

```bash
# 上传到 TestPyPI
uv run twine upload --repository testpypi dist/*

# 从 TestPyPI 安装测试
pip install --index-url https://test.pypi.org/simple/ uvm
uvm --help
```

### 3. 正式发布到 PyPI
```bash
# 上传到正式 PyPI
uv run twine upload dist/*
```

### 4. 验证发布
```bash
# 安装新发布的包
pip install uvm

# 验证功能
uvm --help
uvm list
```

## 发布后工作

### 1. 创建 Git 标签
```bash
git tag -a v0.1.0 -m "Release version 0.1.0"
git push origin v0.1.0
```

### 2. 更新 GitHub Release
1. 去 GitHub 仓库页面
2. 点击 "Releases" 页面
3. 点击 "Create a new release"
4. 选择刚创建的标签
5. 填写发布说明
6. 上传 `dist/` 目录中的包文件

### 3. 更新文档
- 更新 README.md 中的版本信息
- 更新 CHANGELOG.md
- 更新网站文档

## 用户安装指南

发布后，用户可以通过以下方式安装：

### 使用 pip (推荐)
```bash
pip install uvm
```

### 使用 uv
```bash
uv pip install uvm
```

### 从源码安装
```bash
git clone https://github.com/your-org/uvm.git
cd uvm
pip install -e .
```

## 故障排除

### 常见问题

1. **构建失败**
   - 检查 Python 版本是否满足要求 (>=3.9)
   - 检查依赖是否正确安装
   - 查看构建日志中的错误信息

2. **上传失败**
   - 检查 PyPI token 是否正确配置
   - 确认版本号是否已存在
   - 检查网络连接

3. **包内容错误**
   - 使用 `twine check dist/*` 检查包的完整性
   - 确保 `pyproject.toml` 配置正确

### 有用的命令

```bash
# 检查包的完整性
uv run twine check dist/*

# 查看包的元数据
python3 -m zipfile -l dist/uvm-0.1.0-py3-none-any.whl | grep __init__

# 查看包的大小
ls -lh dist/

# 预览将要上传的内容
uv run twine upload --repository testpypi dist/* --verbose
```

## 自动化发布 (CI/CD)

如果需要自动化发布，可以创建 GitHub Actions workflow：

```yaml
name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.9'

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install build twine

    - name: Build package
      run: python -m build

    - name: Publish to PyPI
      env:
        TWINE_USERNAME: __token__
        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
      run: twine upload dist/*
```

这样每次在 GitHub 创建 Release 时就会自动发布到 PyPI。