Gitのデータモデル（とその他のドキュメント更新）
こんにちは！昨年の秋、しばらく時間を取ってGitのドキュメントに取り組むことにしました。オープンソースのドキュメントを改善したいと長いあいだ考えてきました。いつもは、ドキュメントに改善の余地があると感じると、ブログ記事やzineを書いて自分なりに解説してきました。でも今回は、公式ドキュメントそのものを少しでも良くできないだろうかと考えたのです。
そこでMarieさんと一緒に、Gitのドキュメントにいくつかの変更を加えました！
Gitのデータモデル
ドキュメントの作業をしばらく続けるうちに、Gitのドキュメントでは「object」「reference」「index」といった用語が頻繁に登場するのに、それらが何を意味するのか、あるいは「commit」や「branch」といった中核的な概念とどう関係するのかが、十分に説明されていないことに気づきました。そこで、新たに「データモデル」についてのドキュメントを書くことにしたのです。
新しいデータモデルはこちらからご覧いただけます。次のリリース後あたりには、Gitの公式サイトにも掲載されるのではないかと思います。
このドキュメントができたことをとても嬉しく思っています。Gitがコミットやブランチのデータをどのように整理しているかを理解することは、長年にわたってGitの仕組みを考えるうえで大きな助けになってきました。正確で、しかも短い（わずか1600語！）データモデルの解説があることは重要だと考えています。
ただ、「正確に」というのが思ったより簡単ではありませんでした。Gitのデータモデルの基本は理解しているつもりでしたが、レビューの過程で新たな詳細をたくさん学び、かなり多くの修正が必要になりました（たとえば、マージのコンフリクトがステージングエリアにどのように保存されるか、といった点です）。
git pushやgit pullなどの更新
また、Gitの主要なmanページの導入部分の更新にも取り組みました。すぐに気づいたのは、「自分の判断で良かれと思って直してみる」というやり方ではうまくいかないということです。なぜメンテナの方が、私の書いたバージョンのほうが優れていると信じてくれるでしょうか。
オープンソースのドキュメント変更をめぐる議論で、ソフトウェアに精通した2人が「この説明は分かりやすいかどうか」について言い争う場面をよく見かけます（「Xという説明がいいと思う！」「いや、Yのほうがいいよ！」といった具合です）。
これはあまり生産的ではないと感じています。あるソフトウェアを使いこなしているエキスパートは、その説明が初心者にとって分かりやすいかどうかを判断するのが、実はとても苦手だからです。そこで、もう少し根拠に基づいた方法でmanページの問題点を見つける必要がありました。
テストリーダーに協力してもらい問題点を洗い出す
そこでMastodonでテストリーダーを募集し、現行のドキュメントを読んで、分かりにくい点や疑問に思ったことを教えてもらうことにしました。約80人の方からコメントをいただき、本当に多くのことを学べました！
皆さんから本当にたくさんの素晴らしいフィードバックをいただきました。たとえば次のようなものです。
- 理解できなかった用語（pathspecとは何か、「reference」はどういう意味か、「upstream」はGitで特別な意味があるのか、など）
- 具体的に分かりにくいと感じた文章
- 追加してほしい内容の提案（「Xは日常的に使っているので、ここに含めるべきだと思う」といった声）
- 不整合の指摘（「ここではXがデフォルトであるように読めるが、別の箇所ではYがデフォルトとされている」など）
テストリーダーの多くは、Gitを少なくとも5〜10年は使ってきた方々でした。これはとても良い条件だったと思います。Gitを5年以上日常的に使っている方々のグループが、ある一文や用語をどうしても理解できないと感じるのであれば、そのドキュメントはより分かりやすく更新すべきだと、説得力をもって主張できるからです。
この「ソフトウェアのユーザーに既存のドキュメントへコメントしてもらい、見つかった問題を修正する」というやり方は、とてもうまくいったと感じています。今後また試してみたいと思っており、とても楽しみにしています。
manページの変更点
最終的に、次の4つのmanページを更新しました。
git pushとgit pullの変更が、個人的には最も興味深いものでした。これらのページの導入部分を更新しただけでなく、さらに次のような内容も新たに書き加えました。
- 「upstream branch」という用語が何を意味するのかを説明するセクション（以前はほとんど説明されていませんでした）
- 「push refspec」とは何かを整理して説明した記述
こうした変更を通じて、オープンソースのドキュメントを維持することの大変さを実感しました。分かりやすく、かつ正確な文章を書くのは簡単ではありません。時には妥協も必要でした。たとえば「git pushは、push.defaultの設定によっては、現在のブランチにupstreamが設定されていないと失敗することがあります」という一文は少し曖昧ですが、「設定によっては」の正確な中身は非常に複雑で、それをすべて解きほぐすのは大きな仕事になるのです。
Gitへのコントリビュートの進め方について
Gitの開発プロセスを理解するのには少し時間がかかりました。ここで詳しく説明するつもりはありません（それだけで別の記事が一本書けてしまいそうです！）が、簡単にいくつかメモしておきます。
- GitにはDiscordサーバーがあり、コントリビュートを始める人向けの「my first contribution」チャンネルでサポートを受けられます。Discordでは皆さんとても温かく迎えてくれました。
- GitGitGadgetを使って、すべてのコントリビュートを行いました。これにより、普段慣れているGitHubのプルリクエストという形で作業を進められ、GitGitGadgetがそれをGit開発者が使っている方式（パッチを添付したメール）に変換してくれました。GitGitGadgetは素晴らしく機能し、Gitでメールによるパッチ送信の方法を一から学ばずに済んだことをとてもありがたく思っています。
- それ以外は普段使っているメールクライアント（Fastmailのウェブインターフェース）でメールに返信し、メーリングリストの慣習に合わせてテキストを80文字で折り返すようにしました。
また、lore.kernel.orgのメーリングリストアーカイブは見づらいと感じたので、長いスレッドを読みやすくするために自作のgit list viewerを手作りしました。
コントリビュートの進め方や変更のレビューでは、多くの方にお世話になりました。Emily Shafferさん、Johannes Schindelinさん（GitGitGadgetの作者）、Patrick Steinhardtさん、Ben Knobleさん、Junio Hamanoさんをはじめ、多くの皆さんに感謝します。