深入 lazydocker 贡献指南：从 Pull Request 流程到 vendor 依赖管理

本文基于 lazydocker 仓库的 CONTRIBUTING.md 编写，完整讲解该项目的贡献工作流程：从 Fork 分支、编写测试到提交 PR 的七步规范，以及项目特有的 vendor 目录依赖管理方案（含两套可直接复制的依赖升级命令序列）。读完本文，你将能在不破坏项目构建约束的前提下，独立完成 lazydocker 的代码修改、依赖升级、本地测试验证与构建发布流程。

一、贡献总则：一切代码变更都通过 Pull Request 进行

CONTRIBUTING.md 开宗明义：lazydocker 欢迎想学 Go 的开发者参与，因为整个项目就是用它写的；但任何修改在动手之前，应先通过 issue、邮件或其他渠道与维护者讨论你打算做的变更。之后，所有代码变更都必须通过 Pull Request 提交，项目维护者明确“actively welcome your pull requests”。

文档给出的 PR 流程共七步，这里完整继承并结合仓库实际结构逐步拆解：

1. Fork 仓库并从 master 创建分支。这是标准 Fork 工作流，后续依赖升级脚本也以 master 分支为基线（见下文 scripts/bump_gocui.sh）。
2. 如果你新增的代码应当被测试，就添加测试。项目采用 Go 原生测试框架，测试文件与源码同目录、以 _test.go 结尾，例如 pkg/utils/utils_test.go、pkg/commands/os_test.go、pkg/gui/panels/filtered_list_test.go。新增逻辑时，参照同目录已有测试的写法即可。
3. 如果你新增的代码需要文档，就更新文档。项目的用户文档集中在 docs/ 目录，例如 docs/Config.md 及各语言的快捷键文档 docs/keybindings/Keybindings_en.md。
4. 代码尽量遵循 Effective Go 指南。这是 Go 官方编写规范，也是项目对代码风格的核心要求。
5. 务必测试你的修改，验证方式见本文第三节。
6. 写好 commit message，遵循社区通行的 Git 提交信息规范（主题行简明、祈使句、正文说明动机与影响）。
7. 发起 Pull Request。

此外，文档还规定了另外两条底线规则，分别对应后两节：提交代码即表示同意其以 MIT 许可证开源，以及参与项目即表示接受行为准则。

二、为什么要用 vendor 目录：项目的依赖管理策略

这是 CONTRIBUTING.md 中最具项目特色的部分。维护者在“Vendoring”一节解释了选择 vendor 目录的理由：

• 单一事实来源（single source of truth）：所有依赖文件被保存在仓库内的 vendor 目录中，每个 PR 里依赖的变化一目了然；
• 快速试验：方便在各依赖包之间快速尝试、切换版本；
• 编辑器检索：可以直接在编辑器里搜索、阅读依赖包的源码，无需额外拉取。

文档同时坦承代价：项目曾“不情愿地”从 dep 迁移到 Go modules，而 Go modules 对 vendor 目录的支持当时仍存在历史遗留问题，因此操作代码库会有一点额外开销。这个判断可以直接在当前仓库中验证：

• 仓库根目录下确实存在 vendor 目录，存放全部依赖源码；
• go.mod 声明模块路径为 github.com/jesseduffield/lazydocker，go 1.22、toolchain go1.23.6，直接依赖包括 Docker 官方 docker/cli 与 docker/docker 客户端库、终端 UI 库 jesseduffield/gocui（作者维护的分支版本 v0.3.1-0.20240418080333-8cd33929c513）、jesseduffield/lazycore 等——这些都是需要重点关注的依赖包；
• test.sh 在跑测试前显式 export GOFLAGS=-mod=vendor；
• Dockerfile 的构建命令同样带 -mod=vendor 标志。

也就是说，“用 vendor 目录工作”不是文档建议，而是这条项目流水线（测试、构建）的硬性前提。理解了这一点，后面两套操作流程的差异就清晰了。

三、两种依赖操作方式：GOFLAGS 环境变量 vs 逐次显式指定

当需要修改依赖包（例如升级 jesseduffield/gocui）时，CONTRIBUTING.md 给出了两套等价但使用体验不同的操作序列，贡献者可以二选一。

方式一：通过 ~/.bashrc 设置全局 GOFLAGS

思路是把 vendor 模式设为 shell 的默认行为，之后所有 Go 命令自动生效：

1. 在 ~/.bashrc 中加入 export GOFLAGS=-mod=vendor；
2. 用 go run main.go 运行 lazydocker（无需再带任何 -mod 参数）;
3. 如需升级依赖，例如 jesseduffield/gocui，执行：

GOFLAGS= go get -u github.com/jesseduffield/gocui@master
go mod tidy
go mod vendor

这里有一个关键细节：go get 前缀了 GOFLAGS=（空值），临时清空环境变量再执行依赖解析。原因很直观——vendor 模式下 Go 工具链会拒绝更新模块依赖，只有脱离 vendor 模式才能改 go.mod；随后 go mod tidy 整理依赖图，go mod vendor 把新依赖重新同步进 vendor 目录。三步必须按顺序完整执行，缺一不可。

方式二：不改 ~/.bashrc，逐次显式传参

如果你不想动 shell 配置文件（比如不想污染全局环境），则保持默认环境不变：

1. 不改 ~/.bashrc；
2. 用 go run -mod=vendor main.go 运行 lazydocker，把 vendor 模式作为命令行参数显式传入；
3. 升级依赖时执行与方式一相同的三步命令序列，但 go get 不再需要 GOFLAGS= 前缀：

go get -u github.com/jesseduffield/gocui@master
go mod tidy
go mod vendor

两种方式最终状态完全一致，区别只在于 vendor 模式是“环境默认”还是“逐次声明”。从源码结构看，维护者本人也沉淀了可复用的升级脚本：scripts/bump_gocui.sh 与 scripts/bump_lazycore.sh 各用一行完成同样的升级，写法为：

GOPROXY=direct go get -u github.com/jesseduffield/gocui@awesome && go mod vendor && go mod tidy

脚本注释特别说明了两点工程经验：一是 GOPROXY=direct 用于绕过代理服务器缓存滞后的问题（直接连源码仓库解析版本）；二是 go get 必须显式指定分支名（如 master、awesome），否则 Go 会退回到按 semver 标签找默认版本的行为——这对维护者自己 fork 的、以分支为发布单位的依赖包至关重要。

四、如何验证你的修改：测试脚本与手动测试环境

文档第 5 步要求“测试你的修改”，仓库提供了两级验证手段。

自动化测试：test.sh

test.sh 是项目的标准测试入口，值得逐段理解：

export GOFLAGS=-mod=vendor          # 第 6 行：强制 vendor 模式，与 CONTRIBUTING 保持一致
for d in $( find ./* -maxdepth 10 ! -path "./vendor*" ! -path "./.git*" \
           ! -path "./scripts*" -type d); do
    if ls $d/*.go &> /dev/null; then
        args="-race -coverprofile=profile.out -covermode=atomic $d"
        ...
        go test $args                  # 若本机装有 gotest 则改用 gotest
    fi
done

几个要点：

• 先排除 vendor、.git、scripts 目录，再递归发现所有含 .go 文件的包目录，逐包执行 go test，避免跨包并发时的路径问题；
• 每个包都带 -race（竞态检测）与 -coverprofile（覆盖率采集），覆盖率片段追加汇总到 coverage.txt；
• 如果检测到 gotest 命令（Go 测试并行化工具），则自动改用 gotest 加速。

贡献者跑完自己的测试后，也应当跑一遍完整 ./test.sh，确认没有破坏其他包的测试。

手动测试：test/ 目录下的 Compose 环境

test/docker-compose.yml 定义了两个服务（my-service 与 my-service2），各自用 test/Dockerfile（基于 alpine:latest）构建并执行 test/print-random-stuff.sh 持续输出随机内容；其中 my-service 依赖 my-service2 并暴露端口映射。这是一个刻意保持“可观测”的迷你环境，方便贡献者在界面中验证容器列表、依赖关系、端口显示、日志滚动等功能是否正常。开发过程中配合 go run -mod=vendor main.go（或直接 go run main.go，若已设置 GOFLAGS）即可看到实时效果。

构建产物：Dockerfile 中的 vendor 构建

对于关心发布产物的贡献者，Dockerfile 的 builder 阶段展示了最终构建形态：

RUN CGO_ENABLED=0 GOOS=linux GOARCH=${GOARCH} GOARM=${GOARM} \
    go build -a -mod=vendor \
    -ldflags="-s -w \
    -X main.commit=${VCS_REF} \
    -X main.version=${VERSION} \
    -X main.buildSource=Docker"

-mod=vendor 再次印证 vendor 是构建基线；-ldflags 注入的三个变量对应 main.go 中的 commit、version、buildSource 包级变量。而 main.go 的 updateBuildInfo() 还有一条补充路径：当 version 仍为默认值 unversioned 时，会通过 runtime/debug.ReadBuildInfo() 读取 vcs.revision / vcs.time 构建信息，把版本号回退显示为 7 位 commit 短哈希——这解释了为何从源码 go run main.go 启动时版本信息也能正确呈现。

五、许可证与行为准则

CONTRIBUTING.md 的最后两节规定了贡献的法律与社区边界：

• MIT 许可证：所有你提交的代码变更，均被视为与项目主体相同的 MIT 许可（见 LICENSE）文件）。如果你有顾虑，文档明确邀请你联系维护者沟通。
• 行为准则：参与本项目即表示同意遵守仓库内的行为准则文件 CODE-OF-CONDUCT.md。
• 缺陷报告：项目使用 GitHub Issues 跟踪公开 bug，贡献者在开发中遇到疑似缺陷时，通过提交新的 issue 报告即可。

六、贡献者清单速查

把全文浓缩为一份可操作的 checklist：

| 阶段 | 操作 | 依据 | | | | | | 动手前 | 先与维护者讨论变更方案 | CONTRIBUTING.md | | 分支 | 从 master Fork 后创建特性分支 | 同上 | | 编码 | 遵循 Effective Go；新增代码补测试 | 同上 | | 文档 | 涉及用户可见行为时更新 docs/ | 同上 | | 依赖升级 | 方式一/方式二命令序列（go get -u → go mod tidy → go mod vendor） | 同上；参考 scripts/bump_gocui.sh | | 本地运行 | go run -mod=vendor main.go（或设置 GOFLAGS=-mod=vendor 后 go run main.go） | 同上 | | 验证 | ./test.sh（自动带 -race 与覆盖率） | test.sh | | 手动验证 | test/docker-compose.yml 双服务环境 | 同上 | | 提交 | 规范 commit message，发起 PR | CONTRIBUTING.md |

这套流程的核心思想可以概括为一句话：lazydocker 的 vendor 目录是依赖管理的唯一事实来源，任何对依赖的改动都必须以“更新模块 → 整理 → 重新 vendor”三步闭环落盘——遵守这个约束，再配合逐包竞态测试，就是对项目贡献质量最有保证的方式。