go-git 项目贡献指南解读：从 PR 要求到 commit 规范的完整实践

本篇技术指南以 wandb 仓库中随依赖一同 vendored 的 go-git 贡献指南 为核心骨架，系统拆解这一纯 Go 实现的 Git 库的开源协作规范——包括支持渠道、Pull Request 验收标准、分支策略与 commit message 格式。文章同时结合当前仓库中 go-git 的真实使用场景（gitops 模块 与 依赖声明），帮助你既理解"如何向上游 go-git 贡献代码"，也能看懂"wandb 项目自身是如何集成与测试这个依赖"的。

go-git 是什么：一份随 wandb 一起维护的上游贡献规范

go-git 是一个用纯 Go 编写、具有高度可扩展性的 Git 实现库，既提供低层 plumbing API（对象、引用、传输协议），也提供与命令行 git 行为对齐的高层 porcelain API（clone、commit、push 等）。按 go-git README 的描述，它自 2015 年起持续开发，被 Keybase、Gitea、Pulumi 等大量工具广泛使用。本仓库的 core/go.mod 中声明了 github.com/go-git/go-git/v5 v5.19.2 依赖，代码则直接 vendored 在 core/vendor/github.com/go-git/go-git/v5/ 目录下——因此这份 CONTRIBUTING.md 是随库源码一起被带进仓库的上游项目规范，它描述的是如何向 go-git 官方项目提交贡献，而非针对 wandb 本身的贡献流程（wandb 自身的贡献流程见仓库根目录的 CONTRIBUTING.md）。

go-git 项目采用 Apache 2.0 许可证（见 LICENSE），贡献通过 GitHub Pull Request 方式接收。规范明确强调：提交到 go-git 的每一个功能都必须在官方 git 实现中有对应物，不接受官方 git 不存在的特性——这正是 go-git 追求与 git 完全兼容这一目标的直接体现（完整兼容性对照表见 COMPATIBILITY.md）。

支持渠道：提问、报 Bug 与提需求的正规途径

指南为使用者和贡献者划定了两个官方支持渠道：

• 用户问题：在 StackOverflow 的 go-git 标签下提问，适用于使用层面的疑问（如何 clone、如何遍历提交、如何自定义存储等）。
• Bug 报告与功能请求：通过 GitHub Issues 提交。

同时指南给出了一条非常重要的前置动作——在开新 Issue 或提 PR 之前，先搜索项目：很可能你遇到的问题已经有人报告过，或是维护者已知晓的已知问题。先搜索、后提问，既能避免重复劳动，也能让维护者把精力集中在真正的新问题上。这条"先搜索再提问"的原则，同样适用于任何大型开源项目。

How to Contribute：一份 PR 必须满足的验收清单

指南明确指出，Pull Request 是向 go-git 官方项目贡献代码的主要且唯一方式。一份 PR 要被接受，必须逐条通过以下要求：

1. 能用官方 git 复现同一行为：不接受官方 git 实现中没有的功能。这条要求保证了 go-git 不会引入 git 之外的"私货"行为。
2. 行为必须与官方 git 实现一致：即"期望行为"要与 git 官方实现对得上，而不是与某个 fork 或自定义版本对得上。
3. 用自然语言 + Go 最小可复现示例解释实际行为：PR 描述不能只写"修了个 bug"，而要说明在什么上下文中、观察到什么行为，并给出一个能复现该行为的 Go 最小示例（Minimum Working Example）。
4. 代码质量门槛：所有 PR 必须使用地道的 Go（idiomatic Go），按 gofmt 格式化，且不能有 go vet 和 go lint 的任何警告。
5. 测试要求：PR 一般都要包含测试，且测试必须通过。
   • Bug 修复类 PR：必须为新增功能附带一套单元测试。
   • 新特性类 PR：必须附带一套覆盖新功能的单元测试。
6. 维护者评审：无论如何，所有 PR 都必须通过至少一位 go-git 维护者的个人评审。

如何在 wandb 仓库中验证这套 PR 标准的实践效果

这套"行为对齐 + 测试配套"的标准，在 wandb 对 go-git 的实际使用中同样可见一斑。wandb 在 core/internal/gitops/git.go 中集成 go-git，用于探测运行脚本的目录是否为 Git 仓库：

// core/internal/gitops/git.go 中的关键用法
git "github.com/go-git/go-git/v5"

func (g *Git) IsAvailable() bool {
    // 用 go-git 以纯 Go 方式打开仓库，无需依赖命令行 git
    if _, err := git.PlainOpen(g.path); err != nil {
        g.logger.Error("git repo not found", "error", err)
        return false
    }
    return true
}

这里 git.PlainOpen 直接以库的形式打开本地仓库——这正是 go-git "纯 Go、可嵌入程序"定位的典型用法。而对应的测试 core/internal/gitops/git_test.go 则充分演示了 go-git 高层 API 的测试套路：先用 git.PlainInit 在临时目录初始化仓库，再用 repo.Worktree() 拿到工作区、worktree.Add 暂存文件、worktree.Commit 提交，甚至用 baseRepo.CreateRemote 和 baseRepo.Push 搭建本地裸远程仓库来验证上游追踪分支逻辑。这个测试文件本身就是"PR 应附带能复现行为的测试"这一规范的鲜活范例。

gofmt / go vet / go lint：三个必备的 Go 质量工具

指南对代码格式与静态检查提出了明确要求，三者分工不同：

• gofmt：Go 官方的代码格式化工具，统一缩进、对齐与换行风格。gofmt -w 可直接格式化文件。
• go vet：Go 官方静态分析工具，检查代码中的可疑构造（如错误的 Printf 格式串、无意义的赋值、锁误用等）。在 wandb 仓库中，core 目录的 Go 代码同样遵循这一质量基线。
• go lint（golang/lint）：第三方 lint 工具，检查命名、注释、导出的 API 文档等风格问题，与 gofmt、go vet 互补。

实操建议：提交前依次执行 gofmt -l .（列出未格式化文件）、go vet ./... 和 go lint ./...，全部无输出再提交，是满足第 4 条要求的最低成本做法。

分支策略：master 管 v5，新开发走 v6-exp

指南对分支的使用作了严格约定：

• master 分支：仅用于维护 v5 主版本。master 上可接受的变更仅限于：依赖升级（dependency bumps）、Bug 修复，以及其他 v6 不需要的小改动。
• v6-exp 分支：所有新开发都应 targeting v6-exp 分支。
• 回移（backport）机制：如果与至少一位 go-git 维护者达成一致，v6-exp 上的改动可以通过新建一个 targeting master 的 PR 回移到 v5。

这一策略是典型的"主版本稳定 + 下个主版本并行开发"模型：v5 处于维护期，只吸收保守变更；激进的新功能统一进入 v6 的实验分支，避免破坏稳定版本。结合本仓库实际情况，core/go.mod 锁定的正是 v5.19.2，即 wandb 消费的是处于维护模式的 v5 系列——如果你在 wandb 中遇到 go-git 的 bug，修复应 targeting master（v5），而新功能则应先去 v6-exp，这能最大程度减少与上游维护者的来回沟通成本。

Commit message 格式：<package>: <subpackage>, <what changed>. [Fixes #<issue-number>]

指南对 commit message 给出了明确的格式要求，目标是让每个 commit 都能回答三个问题：改了什么、在什么上下文下改的、关联了哪个 issue。官方示例为：

plumbing: packp, Skip argument validations for unknown capabilities. Fixes #623

其形式化描述为：

<package>: <subpackage>, <what changed>. [Fixes #<issue-number>]

逐段拆解：

组成部分	含义	示例
<package>	改动涉及的 go-git 顶层包名	plumbing（低级对象/协议层）、worktree（工作区操作）、remote（远程交互）等
<subpackage>	包内的子包或模块	packp（pack 协议解析）、config、storage 等
<what changed>	用一句话描述实际变更内容	Skip argument validations for unknown capabilities
[Fixes #<issue-number>]	可选的关联 issue 编号	Fixes #623

这种"范围前缀 + 一句话变更 + issue 引用"的格式，让 git log --oneline 的浏览体验极佳：维护者扫一眼前缀就能判断改动归属的模块，通过 issue 编号可以追溯到完整的讨论上下文。这一规范与 git 社区广泛使用的 Conventional Commits 思路一脉相承，也适合作为团队内部 Git 提交规范的参考模板。

总结：把这份指南用起来

• 如果你是 go-git 的潜在贡献者：先搜索既有 issue，再按"行为对齐官方 git、附带最小复现示例、通过 gofmt/vet/lint、补全测试"的清单准备 PR，新功能 targeting v6-exp、v5 修复 targeting master，commit message 遵循 <package>: <subpackage>, <what changed>. 格式。
• 如果你在使用 wandb 中的 go-git（v5.19.2）：参考 gitops 模块 的集成方式与 其测试 的用法，可以快速学会用纯 Go 完成仓库探测、fork point 计算、patch 生成等 Git 操作，无需在运行时依赖命令行 git。
• 如果你在维护任何 Go 项目：这套"先搜索、行为对齐、质量工具把关、测试配套、结构化 commit"的协作规范，本身就是一份可以直接复用的高质量开源治理模板。