发布流程

相关源文件

• .github/workflows/ci.yml
• .github/workflows/release.yml
• CHANGELOG.md
• RELEASE-CHECKLIST.md
• ci/build-and-publish-m2
• crates/cli/src/hostname.rs
• tests/misc.rs
• tests/regression.rs
• tests/util.rs

本文档描述了创建和发布 ripgrep 新版本的完整流程。它涵盖了准备步骤、版本更新、通过 GitHub Actions 进行的自动化构建以及发布后的任务。

概述

ripgrep 的发布流程结合了手动准备和自动化的构建与部署工作流。

发布前准备

依赖管理

1. 确保本地 master 分支与 origin/master 同步
2. 运行 cargo update 并检查 Cargo.lock 中的依赖项更新
3. 运行 cargo outdated 以识别可能需要手动干预的 semver 不兼容更新

内部 crate 更新

Ripgrep 由多个内部 crate 组成，在发布前需要对这些 crate 进行审查和潜在的更新。

对于每个自上次 ripgrep 发布以来有更改的 crate

1. 为该 crate 发布新版本
2. 使用 cargo-up --no-push crates/{CRATE}/Cargo.toml 更新依赖 crate 的最低版本

应按照图表中显示的顺序（从上到下）审查 crate。

来源：RELEASE-CHECKLIST.md10-24

文档更新

1. 更新 crates/core/flags/doc/template.rg.1 中的日期
2. 更新 CHANGELOG.md，包含自上次发布以来的所有值得注意的更改

来源：RELEASE-CHECKLIST.md9 RELEASE-CHECKLIST.md25

创建发布

版本更新与验证

1. 编辑 Cargo.toml 以设置新的 ripgrep 版本
2. 运行 cargo update -p ripgrep 来更新 Cargo.lock
3. 提交更改
4. 运行 cargo package 来验证是否所有内容都能正确打包

或者，使用 cargo-up --no-push --no-release Cargo.toml {VERSION} 来自动化步骤 1-3。

来源：RELEASE-CHECKLIST.md26-30

发布流程图

1. 将更改推送到 GitHub，但不包含标签
2. 等待 CI 工作流（.github/workflows/ci.yml）成功完成
3. 推送版本标签（格式：x.y.z）
4. 这将触发发布工作流（.github/workflows/release.yml）

来源：RELEASE-CHECKLIST.md31-35

自动化发布构建

GitHub Actions 发布工作流由推送到匹配模式 [0-9]+.[0-9]+.[0-9]+ 的标签触发，并包含三个主要作业。

创建发布作业

此作业

• 从标签获取版本
• 验证标签版本是否与 Cargo.toml 中的版本匹配
• 创建一个草稿 GitHub 发布

来源：.github/workflows/release.yml17-40

构建发布作业

此作业为多个平台构建 ripgrep 并创建发布资产。

来源：.github/workflows/release.yml42-283

构建目标

发布工作流为多个平台构建 ripgrep：

目标	操作系统	变体
x86_64-unknown-linux-musl	Linux	静态
i686-unknown-linux-gnu	Linux	glibc
aarch64-unknown-linux-gnu	Linux	glibc
armv7-unknown-linux-gnueabihf	Linux	glibc
armv7-unknown-linux-musleabihf	Linux	静态
armv7-unknown-linux-musleabi	Linux	静态
powerpc64-unknown-linux-gnu	Linux	glibc
s390x-unknown-linux-gnu	Linux	glibc
x86_64-apple-darwin	macOS	Intel
x86_64-pc-windows-msvc	Windows	MSVC
x86_64-pc-windows-gnu	Windows	MinGW
i686-pc-windows-msvc	Windows	MSVC 32 位

来源：.github/workflows/release.yml65-128

构建 Debian 包作业

此作业为 ripgrep 构建 Debian 包 (.deb)。

1. 构建调试二进制文件以生成资源（man 页、补全）
2. 创建 Debian 包结构
3. 构建 .deb 包
4. 将包上传到 GitHub 发布

来源：.github/workflows/release.yml285-371

手动 Apple Silicon 构建

由于 GitHub Actions 不提供免费的 Apple Silicon 运行器，因此需要手动构建。

在 Apple Silicon Mac 上运行：

git checkout {VERSION} && ci/build-and-publish-m2 {VERSION}

来源：RELEASE-CHECKLIST.md44-45 ci/build-and-publish-m21-44

发布后任务

自动化发布流程完成后

1. 将 CHANGELOG.md 的相关部分复制到 GitHub 发布说明中

2. 添加标准的描述文案

   In case you haven't heard of it before, ripgrep is a line-oriented search
   tool that recursively searches the current directory for a regex pattern.
   By default, ripgrep will respect gitignore rules and automatically skip
   hidden files/directories and binary files.
   

3. 发布到 crates.io

   cargo publish
   

4. 更新 Homebrew 公式

   ci/sha256-releases {VERSION} >> pkg/brew/ripgrep-bin.rb
   

   然后编辑文件以更新版本号和 SHA256 哈希。

5. 在 CHANGELOG.md 中添加新的 TBD 部分

   TBD
   ===
   Unreleased changes. Release notes have not yet been written.
   

来源：RELEASE-CHECKLIST.md38-55

发布存档结构

每个发布存档遵循此结构：

ripgrep-{VERSION}-{TARGET}/
├── rg (or rg.exe on Windows)
├── README.md
├── COPYING
├── UNLICENSE
├── LICENSE-MIT
├── complete/
│   ├── rg.bash
│   ├── rg.fish
│   ├── _rg.ps1
│   └── _rg (zsh)
└── doc/
    ├── CHANGELOG.md
    ├── FAQ.md
    ├── GUIDE.md
    └── rg.1 (man page)

来源：.github/workflows/release.yml209-213 .github/workflows/release.yml219-223

版本策略

Ripgrep 遵循语义化版本控制（x.y.z），但采用了一种修改后的方法。

• 自 ripgrep 11 版本以来，主版本号每年都会更新几次。
• 在可能的情况下保持向后兼容性。
• 重大更改会在 CHANGELOG.md 中清晰记录。

来源：CHANGELOG.md117-123 CHANGELOG.md581-593