Git 的資料模型（及其他文件更新）
哈囉！去年秋天，我決定花一些時間來處理 Git 的文件。我一直以來都在思考要投入開源文件工作——通常如果我覺得某個東西的文件可以改進，我會寫一篇部落格文章或一本小誌之類的。但這次我想：能不能直接對官方文件做一些改進呢？
所以我和 Marie（瑪莉） 一起對 Git 文件做了一些修改！
Git 的資料模型
在處理文件一段時間後，我們注意到 Git 在文件中經常使用「object」、「reference」或「index」等術語，但對於這些詞彙的涵義，以及它們與「commit」和「branch」等其他核心概念之間的關聯，卻沒有很好的說明。因此，我們撰寫了一份新的「data model(資料模型)」文件！
目前你可以在這裡閱讀 data model。我想在某個時候（下個版本發布後？）它也會出現在 Git 網站上。
我對此感到很興奮，因為多年來，了解 Git 如何組織其 commit 與 branch 資料確實幫助我理解 Git 的運作方式，而我認為擁有一份簡短（1600 字！）且精準的 data model 非常重要。
「精準」這部分結果證明沒那麼容易：我原本已掌握 Git 的 data model 運作基礎，但在審閱過程中，我學到了一些新的細節，也不得不做了不少修改（例如合併衝突在 staging area(暫存區)中的儲存方式）。
對 git push、git pull 等的更新
我也著手更新了 Git 幾個核心 man page(說明手冊) 的前言。我很快就意識到，「就憑自己的判斷試著改進」是行不通的：維護者為什麼要相信我的版本比較好？
在討論開源文件變更時，我經常看到一個問題：兩位軟體的專家使用者爭論某個解釋是否清楚（「我覺得用 X 來解釋很不錯！嗯，我覺得 Y 會更好！」）
我認為這樣做不太有成效（軟體的專家使用者向來很難判斷某個解釋對非專家是否清楚），所以我需要找到一種更能以證據為基礎、來找出 man page 問題的方法。
找測試讀者來找出問題
我在 Mastodon 上徵求測試讀者來閱讀現行版本的文件，並告訴我他們覺得困惑的地方或有的疑問。大約有 80 位測試讀者留下了意見，讓我收穫良多！
大家留下了大量很棒的回饋，例如：
- 他們不理解的術語（什麼是 pathspec(路徑規格)？「reference」是什麼意思？「upstream(上游)」在 Git 中有特定的涵義嗎？）
- 令人困惑的特定句子
- 建議新增的內容（「我常常做 X，我覺得這裡應該要包含進去」）
- 不一致之處（「這裡暗示預設是 X，但在別處卻暗示預設是 Y」）
大多數測試讀者都已經使用 Git 至少 5 到 10 年，我覺得這樣效果很好——如果一群已經定期使用 Git 5 年以上的測試讀者都覺得某個句子或術語難以理解，就很容易主張應該更新文件，讓它更清楚易懂。
我覺得這種「讓軟體的使用者對現有文件發表意見，然後修正他們發現的問題」的模式效果非常好，也很期待未來有機會再嘗試一次。
man page 的變更
我們最後更新了這 4 個 man page：
對我來說，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 開發者使用的系統（夾帶 patch 的電子郵件）。GitGitGadget 運作得非常好，讓我很慶幸不用學習如何用 Git 以電子郵件寄送 patch。
- 其他時候，我則使用平常的電子郵件用戶端（Fastmail 的網頁介面）來回覆郵件，並將文字以每行 80 個字元換行，因為這是郵件論壇的慣例。
我也覺得 lore.kernel.org 上的郵件論壇封存很難瀏覽，所以我自己拼湊了一個 my own git list viewer，讓閱讀冗長的郵件論壇討論串變得更容易。
許多人在貢獻流程與審閱修改的過程中幫助了我：感謝 Emily Shaffer（艾蜜莉·夏弗）、Johannes Schindelin（約翰尼斯·辛德林）（GitGitGadget 的作者）、Patrick Steinhardt（派崔克·史坦哈特）、Ben Knoble（班·諾布爾）、Junio Hamano（濱野純）等人。
（我正在嘗試 在 Mastodon 上的留言，你可以在此查看留言）