てくなべ (tekunabe)

ansible / network / automation

[Ansible] 新バージョンの Ansible が出るときにどこで情報を得ればよいか


これは Ansible Advent Calendar 2019 の22日目の記事です。


■ はじめに

Ansible は年に1〜2回ほどバージョンアップを重ねています。毎回大量のモジュールが追加されたり、様々な機能追加や変更がなされています。

個人的にはどのような変化があるのか気になるので、調べて試して以下のようにまとめてきました。

この記事では、新しいバージョンの Ansible が登場した(する)際に、私がどこを見て情報を得えてきたかご紹介します。


【目次】


■ 【Porting Guides】バージョンアップ時の注意点は?

docs.ansible.com

Porting Guidesには、各バージョンへアップデート(移行: Proting)する際の注意点などがまとめられています。

具体的には以下のようなものです。

  • 代表的な新モジュールや新機能
  • 仕様変更
  • Deprecated(非推奨)になるモジュールや機能
  • 削除されたモジュールや機能

CHANGELOG を確認する時間がなかったり、ざっくりした変更を知りたい場合には、Porting Guides が適していると思います。

Ansible 2.9 の例: Ansible 2.9 Porting Guide


■ 【公式ブログ】 特に注目な新機能は?

www.ansible.com

THE INSIDE PLAYBOOKRed Hat 社による、Ansible の公式ブログです。

マイナーバージョンアップ(2.8 から 2.9、など)がある前後は、特定の新機能にフォーカスをあてた記事が投稿されることあります。詳細に解説されるため、注意深く読むようにしています。

ただし、サンプルの Playbook のインデントが誤っていることがしばしばあります。サンプルを試してうまく行かないときはインデントを疑うと良いです。

(利用されている CMS のコードブロック機能と YAML の相性があまり良くないようです。)


■ 【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、テストコードなども分かります。

f:id:akira6592:20191217175647p:plain
CHANGELOGのフラグメントがマージされる

以下、具体的な例を元に CHANGELOG の追い方を説明します。

なお、操作説明の都合上 GitHub の画面を利用しますが、VS Code などの GitHub と連携できるエディタを利用して、同等の操作をしていただいても大丈夫です。 また、今回は少ないヒントから追うことを想定して回りくどい追い方をしています。もし、CHANGELOG の文言に PR 番号が含まれていたり、PR を直接検索したりして、元の PR 見つかるのであれば、それはそれでOKです。

CHANGELOG の追い方

(1) 追いたいバージョンの CHANGELOG を表示する

Ansible のリポジトリchangelogs ディレクトリを開きます。

追いたいバージョンのブランチ を選択します。Ansible 2.9 であれば stable-2.9 を選択します。

f:id:akira6592:20191217175741p:plain
changelogs ディレクトリの表示とブランチの選択

(なお、本リポジトリはデフォルトでは 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 の場合はこちらです。

f:id:akira6592:20191217175845p:plain
CHANGELOG フラグメントの一覧

フラグメントの一覧内を、今回追っているCHANGELOG の文言の一部 check_mode で検索します。以下のファイルが見つかります。

f:id:akira6592:20191217175930p:plain
フラグメントの特定

見つかったフラグメントを開き、目的の CHANGELOG フラグメントであることを確認します。

f:id:akira6592:20191217180459p:plain
フラグメントの中身

ここまでで、CHANGELOG フラグメントを特定できました。

(3) 元の PR を特定する

先ほど特定した フラグメントの History ボタンをクリックしてコミット履歴を表示します。

f:id:akira6592:20191217180532p:plain
History をクリック

表示されたコミット履歴のメッセージをクリックします。

f:id:akira6592:20191217180603p:plain
メッセージをクリック

表示された画面を、上にスクロールすると該当 PR へのリンクがあるので、クリックします。

f:id:akira6592:20191217180634p:plain
PR 番号のクリック

f:id:akira6592:20191217180659p:plain
特定できたPR 画面

ここまでで、元の PR を特定できました。PR のやり取りや、トリガーとなった issue(この例では "fixes #48787" とあり)を確認することで、修正の経緯などを知ることができます。

続いて、さらに詳しく知るべく、コードレベルで確認します。

(4) 修正されたコードなどを確認する

先ほど特定した PR の Files changed をクリックすると、この PR 内で修正されたコードの一覧を表示します。

f:id:akira6592:20191217180728p:plain
Files Changed のクリック

f:id:akira6592:20191217180820p:plain
修正ファイルの一覧
この修正されたコードの一覧でかなり詳細を知ることができます。

分かることをいくつかピックアップします。

少々長くなりましたが、以上が CHANGELOG から具体的で詳細な変更点を追う方法でした。

なお、ここで例として追った本機能の使い方については、別途以下の記事にまとめています。

[Ansible] check モードの実行ログに [CHECK MODE] という印をつける方法 - てくなべ (tekunabe)


■ 【ROADMAP】 次のバージョンはいつリリース予定?

docs.ansible.com

ROADMAPには、次バージョンの Ansible がいつ頃、どのような段階でリリースされる予定かが掲載されています。 掲載されるバージョンの単位は、Ansible 2.8、2.9・・のようなマイナーバージョンです。

なお、latest バージョンのドキュメントには、開発中の次のバージョン ROADMAP が載らないので devel バージョンで確認します。

docs.ansible.com

f:id:akira6592:20191217181233p:plain
ドキュメントのバージョン切り替え


■ 【番外編】 もっと普段から情報を追うためには

私が見逃しているだけかもしれませんが、CHANGELOG に載らない変更がなされることもあります(例 PR #59153)。

日常的に新聞を読むように開発状況を追っていくためには、以下の情報


まとめ

新しいバージョンの Ansible が登場した(する)際に、私がどこを見て情報を得えてきたかご紹介しました。

情報源 概要
Porting Guides バージョンアップ時の注意点
公式ブログ 特に注目の機能
CHANGELOG (リンクは Ansible 2.9 の例) 具体的で詳細な変更点
ROADMAP 次のバージョンのリリース予定

Ansible でどのような機能が追加、修正されたかを追う方法として参考になれば幸いです。