贡献指南

设置开发环境

先决条件

要为 fzf 做出贡献，您需要安装以下工具：

Go（1.20 或更高版本），如 go.mod20 中指定
Git
Ruby（用于运行测试）
Bash、Zsh 和 Fish shell（用于测试 shell 集成）
Tmux（用于测试终端集成）

来源：go.mod1-21 .github/workflows/linux.yml26-29 .github/workflows/linux.yml36

克隆和构建 fzf

项目结构

以下图表说明了 fzf 代码库中贡献者可能会接触到的关键组件

核心架构组件

来源：.github/workflows/linux.yml1-49 .github/workflows/macos.yml1-46 BUILD.md1-62

贡献工作流程

以下图表说明了 fzf 项目的标准贡献工作流程

贡献流程图

来源：.github/workflows/linux.yml4-9 .github/workflows/macos.yml4-9

分步流程

派生仓库
- 在 GitHub 上创建您自己的存储库分支
克隆和设置
创建分支
进行更改
- 实现您的功能或修复
- 确保代码遵循项目约定
- 为您的更改添加测试
本地测试
提交并推送
创建拉取请求 (Pull Request)
- 从您的分支提交 PR 到主存储库
- 对于稳定更改，目标是 master 分支；对于实验性功能，目标是 devel 分支
- 提供清晰的更改说明
- 引用任何相关问题

来源：.github/workflows/linux.yml4-9 .github/workflows/linux.yml44-48 .github/workflows/macos.yml1-46

代码风格和约定

fzf 遵循特定的代码风格和约定，以在代码库中保持一致性

Go 代码

遵循标准的 Go 代码约定
使用 go fmt 格式化您的代码
使用 golint 和 go vet 检查问题
为公共函数和类型编写清晰、简洁的注释
根据 go.mod20 中指定的 Go 1.20 兼容性

Ruby（测试套件）

测试遵循 Ruby 风格指南
使用 Rubocop 进行代码检查
运行 make lint 检查风格问题
CI 在 Linux 上使用 Ruby 3.4.1，在 macOS 上使用 Ruby 3.0.0

Shell 脚本

尽可能遵循 POSIX 兼容的 shell 脚本
在所有支持的 shell（bash、zsh、fish）上测试您的 shell 脚本
确保与 Linux 和 macOS 环境兼容

代码组织

组件	位置	风格指南
Go 核心	`src/*.go`	Go 标准格式
Shell 集成	`shell/*`	POSIX 兼容性
测试	`test/*.rb`	Ruby 风格指南
构建系统	`Makefile`	Make 约定
Vim 插件	`plugin/fzf.vim`	Vim 脚本约定

来源：.github/workflows/linux.yml30-33 .github/workflows/linux.yml41-42 .github/workflows/macos.yml27-30 .github/workflows/macos.yml38-39 BUILD.md13-19

测试

fzf 拥有全面的测试套件，所有贡献都应包含相应的测试。

测试类型

测试架构

单元测试
- 位于 Go 测试文件中（后缀为 _test.go）
- 使用 go test ./... 运行
- 单独测试各个 Go 组件
集成测试
- 位于 test/ 目录中
- 用 Ruby 编写
- 测试 fzf 的完整功能
- 包含 test_go.rb 用于 Go 特定集成测试
Shell 集成测试
- 测试 shell 集成脚本
- 确保与 bash、zsh 和 fish 兼容
- 验证按键绑定和补全功能

运行测试

来源：.github/workflows/linux.yml44-48 .github/workflows/macos.yml41-45

持续集成

fzf 使用 GitHub Actions 进行持续集成，以确保代码质量和兼容性。您的拉取请求必须通过所有 CI 检查才能合并。

CI 工作流

CI 管道架构

CI 检查

Linux 工作流
- 运行于 Ubuntu 24.04
- 使用 Go 1.20 和 Ruby 3.4.1
- 安装 zsh、fish 和 tmux 包
- 使用 Rubocop 进行代码检查（make lint）
- 运行单元测试（make test）
- 运行集成测试（ruby test/runner.rb --verbose）
macOS 工作流
- 运行于最新 macOS
- 使用 Go 1.20 和 Ruby 3.0.0
- 通过 Homebrew 安装 fish、zsh 和 tmux
- 使用 Rubocop 进行代码检查
- 运行单元测试（make test）
- 运行 Go 特定集成测试（ruby test/test_go.rb --verbose）
附加检查
- 拼写检查（Typos 工具）
- Go 代码的 CodeQL 分析
- 依赖项审查，检查安全漏洞

来源：.github/workflows/linux.yml1-49 .github/workflows/macos.yml1-46

拉取请求指南

提交拉取请求时，请遵循以下指南，以确保顺利的审查过程

保持 PR 的专注性
- 每个 PR 应解决一个单独的问题
- 避免合并多个不相关的更改
- 将 PR 提交到适当的分支（稳定更改目标 master 分支，实验性功能目标 devel 分支）
撰写清晰的描述
- 解释更改的内容及其原因
- 引用任何相关问题
- 描述任何性能影响
更新文档
- 更新相关文档以反映您的更改
- 为复杂的代码段添加注释
- 为与构建相关的更改更新 BUILD.md
解决 CI 故障
- 修复 CI 系统报告的任何问题
- 确保所有测试在 Linux 和 macOS 上都能通过
- 修复 Rubocop 报告的所有 linting 问题
积极响应反馈
- 对建议和建设性批评持开放态度
- 及时进行请求的更改
- 根据需要 rebase 您的分支以解决冲突

拉取请求审查流程