spool-memory 0.2.3

# Spool 发版流程

本文档描述 spool 的完整发版流程，包括三种安装方式：cargo install、GitHub Releases 直接下载、Homebrew。

## 发版前检查

1. **确保 CI 通过**
   ```bash
   git push origin main
   # 等待 GitHub Actions CI 全部通过
   ```

2. **更新版本号**
   ```bash
   # 编辑 Cargo.toml
   version = "0.2.0"  # 按语义化版本更新
   
   # 编辑 homebrew/spool.rb
   version "0.2.0"
   ```

3. **更新 CHANGELOG**（如果有）

## 发版步骤

### 1. 发布到 crates.io（cargo install）

```bash
# 首次发布需要登录
cargo login

# 发布（会自动构建和上传）
cargo publish

# 用户安装方式
cargo install spool-memory
```

### 2. 触发 GitHub Actions 自动构建

```bash
# 打 tag 触发自动构建
git tag v0.2.0
git push origin v0.2.0

# GitHub Actions 会自动：
# 1. 构建 4 个平台的二进制（macOS Intel/ARM64, Linux x86_64/ARM64）
# 2. 打包成 .tar.gz
# 3. 创建 GitHub Release
# 4. 上传所有二进制到 Release assets
```

查看构建进度：
```bash
gh run list --workflow=build-binaries.yml
gh run watch
```

### 3. 更新 Homebrew Formula

构建完成后，下载各平台二进制并计算 SHA256：

```bash
# 下载 Release assets
cd /tmp
gh release download v0.2.0 --repo lukylong/Spool

# 计算 SHA256
shasum -a 256 spool-macos-arm64.tar.gz
shasum -a 256 spool-macos-intel.tar.gz
shasum -a 256 spool-linux-x86_64.tar.gz
shasum -a 256 spool-linux-arm64.tar.gz
```

更新 `homebrew/spool.rb`：
```ruby
version "0.2.0"
# 替换 PLACEHOLDER_*_SHA256 为实际值
sha256 "实际的 SHA256 值"
```

提交更新：
```bash
git add homebrew/spool.rb
git commit -m "chore: update homebrew formula for v0.2.0"
git push origin main
```

### 4. 创建 Homebrew Tap（首次发布）

如果是首次发布，需要创建独立的 tap 仓库：

```bash
# 在 GitHub 创建新仓库：homebrew-spool
# 仓库必须以 homebrew- 开头

# 克隆并添加 formula
git clone https://github.com/lukylong/homebrew-spool.git
cd homebrew-spool
mkdir Formula
cp /path/to/spool/homebrew/spool.rb Formula/
git add Formula/spool.rb
git commit -m "Add spool formula"
git push origin main
```

用户安装方式：
```bash
brew tap lukylong/spool
brew install spool
```

## 三种安装方式对比

| 方式 | 命令 | 优点 | 缺点 |
|------|------|------|------|
| cargo install | `cargo install spool-memory` | 自动编译最新版本 | 需要 Rust 工具链，编译慢 |
| GitHub Releases | 下载 .tar.gz 解压 | 预编译，即下即用 | 手动管理路径和更新 |
| Homebrew | `brew install lukylong/spool/spool` | 自动管理依赖和更新 | 仅 macOS/Linux |

## 自动化脚本

创建 `scripts/release.sh` 简化流程：

```bash
#!/bin/bash
set -e

VERSION=$1
if [ -z "$VERSION" ]; then
  echo "Usage: ./scripts/release.sh v0.2.0"
  exit 1
fi

echo "🚀 Releasing $VERSION"

# 1. 更新版本号
sed -i '' "s/^version = .*/version = \"${VERSION#v}\"/" Cargo.toml
sed -i '' "s/^  version .*/  version \"${VERSION#v}\"/" homebrew/spool.rb

# 2. 提交版本更新
git add Cargo.toml homebrew/spool.rb
git commit -m "chore: bump version to $VERSION"

# 3. 打 tag 并推送
git tag $VERSION
git push origin main
git push origin $VERSION

echo "✅ Release triggered. Check GitHub Actions for build progress:"
echo "   https://github.com/lukylong/Spool/actions"
```

使用：
```bash
chmod +x scripts/release.sh
./scripts/release.sh v0.2.0
```

## 故障排查

### GitHub Actions 构建失败

```bash
# 查看失败日志
gh run list --workflow=build-binaries.yml
gh run view <run-id> --log-failed

# 本地测试交叉编译
cargo build --release --target aarch64-apple-darwin
```

### Homebrew 安装失败

```bash
# 测试 formula
brew install --build-from-source homebrew/spool.rb

# 审计 formula
brew audit --strict homebrew/spool.rb
```

### crates.io 发布失败

```bash
# 检查 Cargo.toml 元数据
cargo publish --dry-run

# 查看详细错误
cargo publish --verbose
```

## 发版检查清单

- [ ] CI 全部通过
- [ ] 版本号已更新（Cargo.toml + homebrew formula）
- [ ] CHANGELOG 已更新
- [ ] 打 tag 并推送
- [ ] GitHub Actions 构建成功
- [ ] GitHub Release 已创建
- [ ] 所有平台二进制已上传
- [ ] Homebrew formula SHA256 已更新
- [ ] 测试 `cargo install spool-memory`
- [ ] 测试 `brew install lukylong/spool/spool`
- [ ] 测试直接下载二进制