ドキュメント盆栽ではじめるOSSコントリビューション

ドキュメント盆栽ではじめる OSS コントリビューション 2024/09/25 AP Tech Fest 公開版資料 株式会社エーピーコミュニケーションズ iTOC 事業部 ACT 横地 晃 1

はじめに OSS を利用するだけなく、貢献してみたいと思った方はいますか？ とはいえ、ハードルは高いですよね。 では、ドキュメントのちょっとした修正だけだったらどうでしょうか？ そんな「ドキュメント盆栽 (*1)」からはじめてみませんか？ *1: ちょっとしたことを含めたドキュメントをメンテンナスすることを示した造語 2

自己紹介 横地 晃 @akira6592 所属 ・iTOC 事業部 ビジネスデベロップメント部 ACT ・エンジニアリングメンター室（兼） 業務 ネットワーク自動化のご支援 好きな OSS ブログ Ansible てくなべ https://tekunabe.hatenablog.jp/ 3

• https://tekunabe.hatenablog.jp/
• https://twitter.com/akira6592

背景とモチベーション 4

一次情報としての公式ドキュメント 公式ドキュメントって重要ですよね。 個人ブログも分かりやすくて良いですが、正式な情報として提示するには、やはり公 式ドキュメントのような一次情報を利用したいところです。 正確、重要 一次情報 （公式ドキュメントなど） 二次情報 （個人ブログなど） 二次情報 （個人ブログなど） 5

公式ドキュメントも完璧ではない しかし、必要な情報が載ってなかったり、誤っていることもあります。 「分かりにくいな」と思った経験もあるのではないでしょうか？ 6

盆栽チャンス OSS なら自分でメンテナンスするチャンスです。 一次情報は、つくれる ◼ より多くの人に届けられる ◼ レビューをしてもらえる ◼ 自己肯定感が得られる ◼ 登壇やブログだけがアウトプットじゃない、 ドキュメントもアウトプット ◼ 7

（ポエム）生成 AI の時代こそ ChatGPT などで技術的な質問をすると公式ドキュメントなどの情報を元に答えてくれま す。しかし、公式ドキュメントが誤っていれば、答えも誤ってしまうでしょう。 生成 AI の時代こそ、公式ドキュメントのような一次情報を作るスキルが重要に感じて います。 重要 一次情報 * 他のスキルが重要でないなどの主張は含んでいません * ChatGPT を取り巻く利用スキルと仕組みスキル https://note.com/akira6592/n/na8ac8e0569f9 8

• https://note.com/akira6592/n/na8ac8e0569f9

メンテナンスの切り口 9

切り口1: 内容 より分かりやすくする ◼ より充実させる ◼ より適切なサンプル ◼ 実装（新機能、仕様変更など）への追従 ◼ きっと誰かが助かる 10

切り口2: 表記・微修正 用語統一 ◼ typo（スペルミスなど）修正 ◼ リンク切れ修正 ◼ マークアップ上のエラー修正 ◼ 議論が不要なものが多い ので修正しやすい 11

必要な心構え 12

そんなちょっとしたことでいいの？ → いい ちょっとしたことでも役に立ちます。 引用元「はじめての OSSコントリビュート」 P13 @youkidearitai https://speakerdeck.com/youkidearitai/hazimetenoosskontoribiyuto?slide=13 13

• https://speakerdeck.com/youkidearitai/hazimetenoosskontoribiyuto?slide=13

英語は・・・ 世界の共通語は、英語ではなく「下手な英語」 ・・・と誰かから聞いた * もちろん円滑なコミュニケーションのためには上手な方がよいですし、努力も必要でしょう * 翻訳ツールはよく使っています 14

心の穏やかさ 「せっかく貢献してあげてるのに」「報われたくてしょうがない」 という気持ちは、持たない方が心の健康上良いです。 15

良くない例 間違えると迷惑になるケースもあります。 以前、express というフレームワークに大量のお試しらしきプルリクエスト（修正の取り 込みリクエスト）が寄せられました。お試しであれば、お試し用リポジトリでやるべきで す。 マージされずにクローズされた変更の例（ #5867） 参考 https://cyclops-ui.com/blog/2024/02/08/OS-problematic/ https://www.youtube.com/watch?v=o2CSJYXJBpc&t=201s 16

• https://github.com/expressjs/express/pull/5867/files
• https://cyclops-ui.com/blog/2024/02/08/OS-problematic/
• https://www.youtube.com/watch?v=o2CSJYXJBpc&t=201s

必要な知識 17

対象ソフトウェアの理解 まずは仕様や設計の正しい理解 ◼ 正しいことを書くには正しい理解が必要 ◼ いろいろ 土台であり、前提 正しい理解 必要なもの 18

ドキュメントの理解 ◼ ドキュメントの構造 ◼ ◼ スタイルガイド ◼ ◼ ビルド、書式チェック、生成など フォーマット ◼ ◼ 表現、用語の統一、禁止用語（black/white はNGなど） ドキュメント生成の仕組み ◼ ◼ どこに何が書かれているべきかなど Markdown、reStructuredText など 利用ツール、サービス ◼ Read the Docs、Sphinx など 19

リポジトリ上のお作法の理解 git、GitHub の操作 ◼ Code of Conduct（行動規範） ◼ プルリクエストを出すときの対象ブランチ ◼ ◼ ◼ ドキュメントに限らず開発者向けドキュメントに大体書いてある 合意形成の段取り ◼ 大幅な変更や追加は事前に issue などで議論、合意形成が必要 ◼ typo 修正くらいならいきなりでも OK ◼ changelog の必要有無、書き方 ◼ ドキュメントの修正だけなら changelog が不要なことも ◼ CI で changelog がないとエラーになることも ◼ バックポートの出し方 ◼ バージョンを遡りすぎて無い機能の記述をしないように、など実装との整合性に注意 20

ドキュメンテーションの仕組みやお作法の情報源 README.md や CONTRIBUTING.md などを確認 ◼ 既存のプルリクエストを確認 ◼ ◼ ドキュメント関連は「documentation」「docs」のようなラベルがついていることもある 追えばどんな感じで修正してるのか 雰囲気が分かる 21

（参考）Ansible の場合 ◼ リポジトリ作法など ◼ Contributing to the Ansible Documentation ◼ 本体のドキュメントは ansible/ansible-documentation で管理（以前は ansible/ansible） ◼ プルリクエストは devel ブランチへ ▼botが出したバックポートのプルリク例 ◼ バックポートのプルリクエストはほぼ自動化 ◼ コレクション側は各コレクションのリポジトリで管理 ◼ 仕組み ◼ reStructuredText、Sphinx、Markdown を利用 ◼ コードに埋め込まれた情報から生成する箇所もある ◼ antsibull-docs というドキュメントビルドツールがある ◼ スタイルガイド ◼ Ansible documentation style guide 22

• https://docs.ansible.com/ansible/latest/community/documentation_contributions.html
• https://docs.ansible.com/ansible/latest/dev_guide/style_guide/index.html
• https://github.com/ansible/ansible-documentation/pull/1777

私の盆栽コレクション ちょっとしたことだらけ 23

事例1: はじめての修正はたったこれだけ はじめての OSS へのプルリクは、Ansible のドキュメントの サンプルコードの修正 ◼ これだけだけど、達成感はあった ◼ https://github.com/ansible/ansible/pull/43816 24

• https://github.com/ansible/ansible/pull/43816

事例2: 寝てる間にマージ Ansibleのドキュメントでサンプルコードの YAML のインデントずれを微修正 ◼ 議論不要なレベルの微修正ということもあり、 プルリク出して寝て起きたらマージされていた ◼ 時には時差も便利 22:24(JST) にプルリク出して ◼ お風呂入って寝た 翌 00:48(JST) にマージ https://github.com/ansible/ansible-documentation/pull/1776 25

• https://github.com/ansible/ansible-documentation/pull/1776

事例3: 混乱されがちなことを補足 Ansible のネットワークモジュール利用時の、サーバーと異なる点を追記 ◼ 時々話題になるわりにはドキュメントに載ってなかったので ◼ ◼ ブログに書こうと思ったけど、どうせなら・・ 追記 network_cli 利用時は、file モジュールな どはコントロールノードで動くよ https://github.com/ansible/ansible-documentation/pull/1051 26

• https://github.com/ansible/ansible-documentation/pull/1051

事例4: 少し議論があったパターン Ansible のサンプルで省略表記の修正をプルリク ◼ 追記の提案があったのて取り入れた ◼ 省略表記の「...」を含めてコピペするとエ ラーになるからコメントに https://github.com/ansible/ansible-documentation/pull/1114 省略表記の存在を理解してもらうための 注意書きを提案されて追記した 27

• https://github.com/ansible/ansible-documentation/pull/1114

事例5: おわかりいただけただろうか ぱっと見では分からないけど、コピペするとエラーになる箇所を修正 ◼ 「-」であるべきところが「–」だった ◼ U+2013 en dash Before After U+002D hyphen https://github.com/ansible/vscode-ansible/pull/611 28

• https://github.com/ansible/vscode-ansible/pull/611

事例6: CLA の同意が必要なパターン Azure のドキュメントのサンプルコードの微修正をプルリク ◼ CLA（Contribution License Agreement）の同意を求めるコメントがつく ◼ 確認して同意すると「signed」に ◼ CLA 同意の操作をすると 「signed」になった 該当のPR https://github.com/MicrosoftDocs/azure-dev-docs/pull/705 流れの解説 https://tekunabe.hatenablog.jp/entry/2022/02/02/azure_document_pr 29

• https://github.com/MicrosoftDocs/azure-dev-docs/pull/705
• https://tekunabe.hatenablog.jp/entry/2022/02/02/azure_document_pr

番外編: 質問がドキュメント更新のきっかけに Ansible Forum で特殊な「namespace」について質問 ◼ これをきっかけに他の方がドキュメントに追記してくれた ◼ ローカルで利用できる namespace っ てありますか？ …(略)… （前にも似た質問があったし） ドキュメントに追記しておくよ！ https://forum.ansible.com/t/the-namespace-for-the-collection-used-only-within-the-organization/2896 追記された 30

• https://forum.ansible.com/t/the-namespace-for-the-collection-used-only-within-the-organization/2896

やってみたいと思ったら 31

やってみたい思ったら ◼ Slack の専用チャンネル で相談 ◼ ◼ GitHub 上の操作の練習に誰かが付き合ってくれるかも Ansible のドキュメントでしたら、簡単な修正ネタをストックしているので、上記チャン ネルにご参加のうえ、横地にお声がけください 32

まとめ 33

まとめ 一次情報は、つくれる ◼ 登壇やブログだけがアウトプットじゃない、ドキュメントもアウトプット ◼ ちょっとした修正でもいい ◼ 対象ソフトウェアの理解が前提 ◼ お作法やドキュメントの仕組みの理解も必要 ◼ 34