はじめに
7月頃にたまたまTerraformのAWS Providerのドキュメントに一部誤りを見つけ、
勇気を出して初めてのPull Requestを作った & めでたくマージしてもらいました。
→ Update rds_global_cluster.html.markdown #9187
AWS Providorのリソース: rds_grobal_clusterに関して、
ドキュメントの "Argument Reference" 入力必須である引数 "global_cluster_identifier" が書かれていないことに気づき修正したものです。
非常に小さいPRですが、OSS活動初心者目線での知見の共有が
今後Terraformをより良くしていく人を増やすためのきっかけになれば幸いです。
想定読者
- Terraformコミュニティへの貢献に挑戦してみたいと思っている人
- Terraformのドキュメントに誤りを発見したけれどもどこから報告したらいいかわからない人
ドキュメントコントリビュートの流れ
修正箇所を特定する
Terraform公式のCommunityページを参照すると、
Hashicorp社の持つ各種Providorのissueなどは
https://github.com/terraform-providers
で管理されていることがわかりました。
今回は後者のオーガニゼーションから対象リポジトリにたどり着きました。
更に、AWS Providorの場合、ドキュメント類はこちらのディレクトリに集約してあるようでした。
(※ d/ ディレクトリはdatasource, r/はresource, guide/ はprovidor自身のガイド)
コントリビューションガイドラインを探す
プロバイダのREADME.mdから飛べるガイドラインを一読しておきます。
ドキュメント更新も含め、コントリビューション時に気をつけるべき心得が書いてあります！
修正
プルリク一覧を検索し、既に同様のプルリクが出ていないかを確認したら
修正に取り掛かります。
GitHubにおけるOSS修正の一連の流れはこちらがとても勉強になります！
→GitHubでフォークしてプルリクしてOSSにコントリビューションする
また今回参加してるterraform Advent Calendar 2019 7日目の yutachaos さんの素敵な記事も
是非に是非にご参照ください！
→ Terraform Registryに初めてcontributeしたときの話
Pull Request
修正したらいよいよPullRequestを出します。
本文はあらかじめ用意されたテンプレートに沿いつつ、直近他の方が出されてMarge済みのドキュメント修正のPRを参考に書いたところ、無事1日以内にマージいただくことができました。
反省点
Pull requestに対して感謝のコメントを頂いたものの（とてもありがたく嬉しいものですね）、
以下のご指摘をいただきました。
Relating to the inclusion of forces new resource for arguments, please note that we do not typically intend to include this information with every resource documentation page as the Terraform plan output will show which can update in place as necessary and the documentation can easily become out of sync with the resource logic.
(筆者拙訳: "forces new resource"に関する記述はなくてもterraform plan 時に気づけるし、今後実際のロジックとの同期が大変になる可能性があるため、すべてのリソースのページに含めるつもりはないので注意してください)
ということで、今後はこの点に関する修正は控えるようにしたいと思います。
ここに関してのみ更にPRを出すのは却ってレビュアーの方の手間を増やすのではないかと踏みとどまりましたが、そのあたりの温度感(直すべき or このままでよい)おわかりの方がいらしたら教えていただきたいです…。
まとめ
反省は残りつつ、ドキュメント更新を通してTerraformへ貢献することができました。
改めてこの記事が今後Terraformをより良くしていく人を増やすためのきっかけになれば幸いです。