Git 的数据模型（及其他文档更新）
你好！去年秋天，我决定花一些时间来改进 Git 的文档。很长一段时间以来，我一直想参与开源文档的工作——通常如果我觉得某个内容的文档可以改进，我会写篇博客文章或做个小册子之类的。但这一次我在想：能不能直接对官方文档做一些改进呢？
于是，我和 Marie（玛丽）一起对 Git 文档做了一些修改！
Git 的数据模型
在参与文档工作一段时间后，我们注意到 Git 在文档中频繁使用“object(对象)”、“reference(引用)”或“index(索引)”等术语，却没有很好地解释这些术语的含义，以及它们与“commit(提交)”和“branch(分支)”等其他核心概念之间的关系。于是我们写了一份新的“数据模型”文档！
你现在可以在此处阅读数据模型。我猜在某个时候（下个版本发布后？）它也会出现在 Git 官网上。
我对此感到很兴奋，因为这些年来，理解 Git 如何组织提交和分支数据确实帮助我更好地理解了 Git 的工作原理，而且我认为拥有一份简短（1600 字！）且准确的数据模型说明非常重要。
“准确”这部分事实证明并不容易：我原本了解 Git 数据模型的基本原理，但在审阅过程中我学到了一些新的细节，不得不做了相当多的修改（例如合并冲突在暂存区中的存储方式）。
对 git push、git pull 等的更新
我还着手更新了 Git 一些核心手册页的引言部分。我很快意识到，“仅凭自己的判断去尝试改进”是行不通的：维护者为什么要相信我的版本更好呢？
在讨论开源文档修改时，我经常看到这样一个问题：软件的两个资深用户争论某段解释是否清晰（“我觉得用 X 来解释会很好！嗯，我觉得 Y 会更好！”）
我认为这种争论没什么成效（众所周知，软件的资深用户往往很难判断某段解释对非专业用户是否清晰），所以我需要找到一种更有依据的方法来发现手册页中的问题。
邀请试读者来发现问题
我在 Mastodon 上招募了试读者，请他们阅读现有版本的文档，并告诉我他们觉得困惑的地方或产生的疑问。大约有 80 位试读者留下了评论，我从中学到了很多！
人们留下了大量宝贵的反馈，例如：
- 他们不理解的术语（什么是 pathspec(路径规范)？“引用”是什么意思？“upstream(上游)”在 Git 中是否有特定含义？）
- 令人困惑的具体句子
- 建议补充的内容（“我经常做 X，我觉得这里应该加上”）
- 不一致之处（“这里暗示 X 是默认值，但在别处又暗示 Y 是默认值”）
大多数试读者都已经使用 Git 至少 5 到 10 年了，我觉得这效果很好——如果一群定期使用 Git 5 年以上的试读者都觉得某句话或某个术语难以理解，那就很容易论证文档应该更新得更清晰一些。
我觉得这种“让软件用户对现有文档发表评论，然后修复他们发现的问题”的模式效果非常好，我很期待将来有机会再次尝试。
手册页的修改
我们最终更新了以下 4 个手册页：
对我来说，git push 和 git pull 的改动最有意思：除了更新这些页面的引言，我们最终还编写了：
进行这些修改让我真切体会到维护开源文档需要付出多少工作：要写出既清晰又准确的内容并不容易，有时我们不得不做出妥协，例如句子“git push may fail if you haven’t set an upstream for the current branch, depending on what push.default is set to.”有点含糊，但“depending”究竟指什么的精确细节非常复杂，要理清它是一项大工程。
关于向 Git 贡献的流程
我花了一段时间才理解 Git 的开发流程。我不打算在这里详细描述（那可能得另写一篇长文！），但有几点简要说明：
- Git 有一个 Discord 服务器，其中有“my first contribution”频道，用于帮助新手入门贡献。我发现 Discord 上的人非常友好。
- 我使用 GitGitGadget 提交了所有的贡献。这意味着我可以发起 GitHub pull request（我熟悉的工作流程），而 GitGitGadget 会将我的 PR 转换为 Git 开发者使用的系统（附带补丁的邮件）。GitGitGadget 运行得很好，我非常庆幸不必去学习如何用 Git 通过邮件发送补丁。
- 除此之外，我使用自己常用的邮件客户端（Fastmail 的网页界面）来回复邮件，并将文本换行到每行 80 个字符，因为这是邮件列表的惯例。
我还觉得 lore.kernel.org 上的邮件列表归档很难浏览，所以我临时拼凑了一个我自己的 git 列表查看器，以便更轻松地阅读冗长的邮件列表讨论串。
许多人在贡献流程和审阅修改方面给予了我帮助：感谢 Emily Shaffer（艾米莉·谢弗）、Johannes Schindelin（约翰内斯·申德林）（GitGitGadget 的作者）、Patrick Steinhardt（帕特里克·斯坦哈特）、Ben Knoble（本·诺布尔）、Junio Hamano（滨野纯）等人。
（我正在尝试在 Mastodon 上的评论，你可以在此查看评论）