これは Ansible Advent Calendar 2019 の22日目の記事です。
■ はじめに
Ansible は年に1〜2回ほどバージョンアップを重ねています。毎回大量のモジュールが追加されたり、様々な機能追加や変更がなされています。
個人的にはどのような変化があるのか気になるので、調べて試して以下のようにまとめてきました。
- Ansible 2.8
- Ansible 2.9
この記事では、新しいバージョンの Ansible が登場した（する）際に、私がどこを見て情報を得えてきたかご紹介します。
【目次】
- ■ 【Porting Guides】バージョンアップ時の注意点は？
- ■ 【公式ブログ】 特に注目な新機能は？
- ■ 【CHANGELOG】 具体的で詳細な変更点は？
- ■ 【ROADMAP】 次のバージョンはいつリリース予定？
- ■ 【番外編】 もっと普段から情報を追うためには
- まとめ
■ 【Porting Guides】バージョンアップ時の注意点は？
Porting Guidesには、各バージョンへアップデート（移行: Proting）する際の注意点などがまとめられています。
具体的には以下のようなものです。
- 代表的な新モジュールや新機能
- 仕様変更
- Deprecated（非推奨）になるモジュールや機能
- 削除されたモジュールや機能
CHANGELOG を確認する時間がなかったり、ざっくりした変更を知りたい場合には、Porting Guides が適していると思います。
Ansible 2.9 の例: Ansible 2.9 Porting Guide
■ 【公式ブログ】 特に注目な新機能は？
THE INSIDE PLAYBOOKは Red Hat 社による、Ansible の公式ブログです。
マイナーバージョンアップ（2.8 から 2.9、など）がある前後は、特定の新機能にフォーカスをあてた記事が投稿されることあります。詳細に解説されるため、注意深く読むようにしています。
ただし、サンプルの Playbook のインデントが誤っていることがしばしばあります。サンプルを試してうまく行かないときはインデントを疑うと良いです。
（利用されている CMS のコードブロック機能と YAML の相性があまり良くないようです。）
I think snippet of "During fact gathering" is wrong indent.
— よこち(yokochi) (@akira6592) 2019年10月14日
How does this one?
The second screenshot should be correct. https://t.co/rs3rhUVOCS pic.twitter.com/aOOmBdgmfu
■ 【CHANGELOG】 具体的で詳細な変更点は？
（リンクは Ansible 2.9 の例） github.com
CHANGELOG には、変更点が細かく掲載されています。
ただ私の感覚としては、CHANGELOG の文言だけでは、何のことを指しているのか、どういう経緯なのかが分からないことがあります。
ここでは少し掘り下げて、CHANGELOG の文言から変更の概要と詳細を方法をご紹介します。
（予備知識） CHANGELOG の作られ方
具体的な CHANGELOG の追い方の説明の前に、CHANGELOG の作られ方について説明します。 作られ方が分かると追い方が分かるようになります。
新モジュール、新プラグイン以外の Pull Request (以下、PR) には、CHANGELOG のフラグメント（かけら）も一緒に含まれます。 そして、リリース時にフラグメントがマージされて、1つの CHANGELOG ファイルにまとめまれます。
つまり、CHANGELOG の文言を頼りにしてフラグメントを特定することで、対応する PR が分かります。 中には親切に CHANGELOG の文言の中に PR や Issue 番号が含まれていることもあります。
PR が分かれば、元になっている Issue、具体的なコードの diff、テストコードなども分かります。
以下、具体的な例を元に CHANGELOG の追い方を説明します。
なお、操作説明の都合上 GitHub の画面を利用しますが、VS Code などの GitHub と連携できるエディタを利用して、同等の操作をしていただいても大丈夫です。 また、今回は少ないヒントから追うことを想定して回りくどい追い方をしています。もし、CHANGELOG の文言に PR 番号が含まれていたり、PR を直接検索したりして、元の PR 見つかるのであれば、それはそれでOKです。
CHANGELOG の追い方
(1) 追いたいバージョンの CHANGELOG を表示する
Ansible のリポジトリの changelogs ディレクトリを開きます。
追いたいバージョンのブランチ を選択します。Ansible 2.9 であれば stable-2.9 を選択します。
（なお、本リポジトリはデフォルトでは devel ブランチが指定されています。devel は開発中のブランチであるため、まだ CHANGELOG は1つにマージされていません。）
特定のバージョンの CHANGELOG が表示されたら、追いたい CHANGELOG の文言を決めます。
ここでは、Ansible 2.9.0 の CHANGELOG の以下の文言を追うことにします。（だいぶ親切に書かれていますが）
Add new option to default standard out callback plugin, ANSIBLE_CHECK_MODE_MARKERS, which adds check mode markers (DRY RUN, CHECK_MODE) to the output when running in check mode. It is off by default.
(2) CHANGELOG フラグメントを特定する
先ほど決めた CHANGELOG の文言の一部を利用して、CHANGELOG フラグメントを特定します。
フラグメントの一覧は changelogs/fragments ディレクトリ内にあります。Ansible 2.9 の場合はこちらです。
フラグメントの一覧内を、今回追っているCHANGELOG の文言の一部 check_mode で検索します。以下のファイルが見つかります。
見つかったフラグメントを開き、目的の CHANGELOG フラグメントであることを確認します。
ここまでで、CHANGELOG フラグメントを特定できました。
(3) 元の PR を特定する
先ほど特定した フラグメントの History ボタンをクリックしてコミット履歴を表示します。
表示されたコミット履歴のメッセージをクリックします。
表示された画面を、上にスクロールすると該当 PR へのリンクがあるので、クリックします。
ここまでで、元の PR を特定できました。PR のやり取りや、トリガーとなった issue（この例では "fixes #48787" とあり）を確認することで、修正の経緯などを知ることができます。
続いて、さらに詳しく知るべく、コードレベルで確認します。
(4) 修正されたコードなどを確認する
先ほど特定した PR の Files changed をクリックすると、この PR 内で修正されたコードの一覧を表示します。
分かることをいくつかピックアップします。
- default コールバックプラグインのコード
lib/ansible/plugins/callback/default.pyの修正により、本機能が実装されている、- 埋め込まれているドキュメントにより、
check_mode_markersオプションが追加され、型はbool、デフォルトはnoである。（埋め込みドキュメントを元にこのページが生成される）
- 埋め込まれているドキュメントにより、
- テストコード
test/integration/targets/callback_default/callback_default.out.check_markers_dry.stdoutの追加により、期待する挙動が分かる。具体的には、Playbook 実行時に check mode で実行されるタスクのログには[CHECK MODE]が付記されることを期待している。
少々長くなりましたが、以上が CHANGELOG から具体的で詳細な変更点を追う方法でした。
なお、ここで例として追った本機能の使い方については、別途以下の記事にまとめています。
[Ansible] check モードの実行ログに [CHECK MODE] という印をつける方法 - てくなべ (tekunabe)
■ 【ROADMAP】 次のバージョンはいつリリース予定？
ROADMAPには、次バージョンの Ansible がいつ頃、どのような段階でリリースされる予定かが掲載されています。 掲載されるバージョンの単位は、Ansible 2.8、2.9・・のようなマイナーバージョンです。
なお、latest バージョンのドキュメントには、開発中の次のバージョン ROADMAP が載らないので devel バージョンで確認します。
■ 【番外編】 もっと普段から情報を追うためには
私が見逃しているだけかもしれませんが、CHANGELOG に載らない変更がなされることもあります（例 PR #59153）。
日常的に新聞を読むように開発状況を追っていくためには、以下の情報
- Issue
- PR
- コミットログ
- 日々大量にコミットされるので、関心のあるディレクトリ配下に絞っても
- モジュールは、主に
lib/ansible/modules配下 やlib/ansible/module_utils配下 - ドキュメントは、
docs配下
- モジュールは、主に
- 日々大量にコミットされるので、関心のあるディレクトリ配下に絞っても
- Project Board
まとめ
新しいバージョンの Ansible が登場した（する）際に、私がどこを見て情報を得えてきたかご紹介しました。
| 情報源 | 概要 |
|---|---|
| Porting Guides | バージョンアップ時の注意点 |
| 公式ブログ | 特に注目の機能 |
| CHANGELOG （リンクは Ansible 2.9 の例） | 具体的で詳細な変更点 |
| ROADMAP | 次のバージョンのリリース予定 |
Ansible でどのような機能が追加、修正されたかを追う方法として参考になれば幸いです。
