本記事はvExperts Advent Calendar 2023の2日目の記事になります。
今年も引き続きAnsibleネタになりますがご了承くださいｗ
と、言うことでAnsibleのcommunity.vmwareでは絶賛メンテナーを募集中です！
ただ「メンテナーはハードルが高いけど気軽にコントリビュートしてみたい」と興味を持っていただいている方もいるかも！と期待を持って簡単にですがコントリビュートの方法をまとめてみたいと思います。
ちなみにコミュニケーションは英語になりますが、英語が苦手な方でも現代ではDeepLやChatGPTなどサポートしてくれるツールがあるのでハードルはとても低くなったと思います。（便利な世の中になりましたね）
モジュールのバグを見つけた！
もし、モジュールを使って想定通りに動作しないようなバグを発見した場合は是非 issue を作って下さい！
利用者からのフィードバックが品質を向上させていくのでとても助かります！
手順
Issueは以下の手順で作成できます。
(1) Issues ページの New issue をクリックします。
(2) 次に Bug report の Get started をクリックします。
(3) Issue: Bug report のページが開きますのでタイトルと以下の情報を記述してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 |
##### SUMMARY 問題の概要を簡単にでよいので記述してください ##### ISSUE TYPE - Bug Report ##### COMPONENT NAME 不具合があるモジュール名を記述してください ##### ANSIBLE VERSION モジュールを実行したAnsibleのバージョンを記述してください 以下のコマンドでバージョンを確認することができます ansible --version ##### COLLECTION VERSION 使用したコレクションのバージョンを記述してください ##### CONFIGURATION Anisbleの設定差分を記述してください 以下のコマンドで差分を出力することができます ansible-config dump --only-changed ##### OS / ENVIRONMENT Ansibleを実行したOSや環境を記述してください ##### STEPS TO REPRODUCE どういう手順を実行して不具合が発生したのか？を具体的に記述してください ##### EXPECTED RESULTS モジュールを実行した結果、期待していた状態はどういうものか？を記述してください ##### ACTUAL RESULTS 実際にモジュールを実行した結果を記述してください |
最後に画面右下にある Submit new issue をクリックしてください。
モジュールの新機能をリクエストしたい！
community.vmwareの開発者はVMwareの全ての機能を把握しているわけではないため、もし追加してほしいモジュール（機能）などがあればリクエストをお願いします！
手順
機能のリクエストもIssuesと同じ手順で作成することができます。
(1) Issues ページの New issue をクリックします。
(2) 次に Feature request の Get started をクリックします。
(3) Issue: ✨ Feature request のページが開きますのでタイトルと以下の情報を記述してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
##### SUMMARY 追加して欲しい機能やモジュールの概要を記述してください ##### ISSUE TYPE - Feature Idea ##### COMPONENT NAME 希望するプラグインやモジュールなどの名前が思いつけば記述してください ##### ADDITIONAL INFORMATION 何故そのモジュールや機能が必要なのか、どういうシーンで有効なのか？などあれば記述してください もし、希望する機能のAPIが分かれば、そのAPI仕様が書かれているドキュメントのリンクがあるとすごく助かります |
モジュールの利用シーンなどがあった方が開発者側で必要性を理解できるため開発のモチベーションに繋がります。
ただし、VMwareのAPI(vSphere Web Services API)でコールできない機能の場合は実装できないため、そこはご了承ください。
新しいモジュールやパッチを作ってみたい！
実際にcommunity.vmwareモジュールの開発に参加してみたい方向けに情報をまとめておきます！
以下は公式ドキュメントの開発ガイドラインになります。
community.vmwareのモジュールではpyvmomiというPythonでESXiやvCenterのvSphere Web Services APIを操作するSDKを使用しています。
そのため、PythonとvSphere Web Services APIとSDKの使い方を理解する必要があります。
pyvmomiにはコミュニティーサンプルがあるので、こちらである程度動作の仕組みが学習できると思います。
以前、簡単に説明している資料を作成したので、こちらも参考にしてみてください 🙂
手順
新しいモジュールの追加、またはバグ修正などのフローは以下のステップになります。
(1) アップストリームから開発者のネームスペースにリポジトリをフォークします。
(2) 開発環境を作成します
|
1 2 3 4 5 |
$ python3 -m venv venv $ . venv/bin/activate (venv) $ pip install --upgrade pip (venv) $ pip install ansible-core pyvmomi git+https://github.com/ansible-network/collection_prep |
(3) フォークしたリポジトリを開発環境にクローンします（gitの設定関連は省略します）
|
1 2 |
$ git clone https://github.com/USERNAME/community.vmware.git collections/ansible_collections/community/vmware |
(4) 修正用のブランチを作成します
|
1 2 3 4 5 6 |
$ cd collections/ansible_collections/community/vmware $ git checkout -b BRANCH_NAME <- 任意の名前に変更してください $ git branch * BRANCH_NAME main |
(5) モジュールの開発またはバグ修正を実施します
(6) モジュールの動作を確認するPlaybookを作成して動作確認をします
(7) モジュールのsanity（構文チェックなどの静的テスト）テストを実行します、このテストは標準で実行されるのでパスしないとマージできません
以下の例では vmware_guest モジュールに対してsanityを実行しています。
|
1 2 3 |
$ cd collections/ansible_collections/community/vmware $ ansible-test sanity vmware_guest |
(8) モジュールまたは機能の追加をした場合はインテグレーションテストを追加してください
インテグレーションテストはモジュールを実際に動作させるテストになります。
テスト自体はRoleで記述します。
以下のディレクトリを参考にしてみてください。
(9) もし、モジュールに記述しているドキュメント（DOCUMENTATIONやEXAMPLESなど）を変更した場合は以下のコマンドを実行してドキュメントを再生成します
以下コマンドを実行すると docs/ 配下にSphinxのドキュメントが生成さます。
|
1 2 |
$ collection_prep_add_docs -p . |
(10) 最後に変更ログのファイルを changelogs/fragments に作成します、もし fragments ディレクトリが無い場合は作成してください
ファイル名は MR番号 or Issue番号_モジュール名.yml で書くことが多いです。
変更ログの種類はこちらを参照ください。
以下はマイナーチェンジの例になります。
|
1 2 3 |
minor_changes: - add moid property in the return value for the module(https://github.com/ansible-collections/community.vmware/pull/1855). |
以下は変更ログを保存したディレクトリ構成例です。
|
1 2 3 4 5 6 |
changelogs ├── changelog.yaml ├── config.yaml └── fragments └── 1855_vmware_dsv_portgroup_info.yml |
(10) 作業が完了したらコミットしてフォークしたリポジトリにブランチをプッシュしてください
(11) プッシュ後、アップストリームにプルリクエストを作成します
AnsibleのCollectionはGitHubフローを採用しているため main ブランチに対してプルリクエストを作成します。
プルリクエスト時は以下の情報を記載ください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
##### SUMMARY バグ修正なのか新規モジュール追加なのか目的や変更が必要な理由の概要を記述してください 関連しているIssueがある場合は以下のように記述してください fixes: IssueのURLを記述 ##### ISSUE TYPE - Feature Pull Request ##### COMPONENT NAME 追加・修正したファイルを記述してださい ##### ADDITIONAL INFORMATION その他に情報があれば記述してください |
後は、CIとメンテナーからのレビューで問題が無ければ無事マージされ（るはず）ます！
是非興味がある方は挑戦してみてください！
