Ansible 開発ライフサイクル

Ansible 開発サイクルは 2 つのレベルで行われます。マクロレベルでは、チームプランがリリースされ、ロードマップおよびプロジェクトを使用して進捗を追跡します。ミクロレベルでは、各プル要求には独自のライフサイクルがあります。

マクロ開発: ロードマップ、リリース、およびプロジェクト

今後のリリースに向けて Ansible にどのような機能が追加されるのか、どのようなバグが修正されるのかについてのやりとりを見逃さないようにしたい場合は、これらのリソースをフォローしてください。

マイクロ開発: プル要求のライフサイクル

Ansible は、プル要求 (略して「PR」) を通じてコードを受け入れます。GitHub は、プル要求プロセスの一般的な仕組みについて の概要を提供します。プル要求の最終目標は、マージされ、Ansible Core の一部になることです。以下は、プル要求ライフサイクルの概要です。

  • プル要求を開きます
  • Ansibot がプル要求をレビューします。
  • Ansibot がラベルを割り当てます。
  • Ansibot がメンテナーに通知します。
  • Shippable テストスイートを実行します。
  • 開発者、メンテナー、コミュニティーがプル要求をレビューします。
  • 貢献者が、レビューアーからのフィードバックに対処します。
  • 開発者、メンテナー、コミュニティーが再度レビューします。
  • プル要求をマージまたは終了します。

自動プル要求確認: ansibullbot

Ansible は多くのプル要求を受け取るため、またこのコミュニティーは自動化に興味があるため、Ansibullbot (略して Ansibot) と呼ばれるツールを使ってプル要求を確認してマージするプロセスのいくつかのステップを自動化しました。

Ansibullbot は多くの機能を提供します。

  • プル要求の提出者に迅速に対応し、プル要求提出のお礼を伝えます。
  • 影響を受けるファイルのプル要求をレビューするコミュニティーメンテナーを指定します。
  • プル要求の現在の状態を追跡します。
  • 責任を負う可能性のあるプル要求の作業を思い出させるために、責任者に通知します。
  • メンテナーは、ワークフローを通じてプル要求に対応する機能を提供します。
  • プル要求は、それを提出したユーザーが中断したり、修了することができるようにします。
  • メンテナーが中断したモジュールを特定し、新しいメンテナーを見つけられるようにします。

Ansibot ワークフロー

Ansibullbot は継続的に実行されます。通常、提出した問題やプル要求の内容は、30 分以内に確認できます。Ansibullbot は、リポジトリー内のすべての未解決のプル要求を調べて、以下のワークフローに従って状態を強制します。

  • プル要求にワークフローラベルがない場合は、new と見なされます。プル要求に含まれるファイルが特定され、ボットがそのファイルのメンテナーに通知を送り、プル要求を確認する方法が指示されます。(注記: 時々、プル要求からラベルを削除して、このプロセスを「再起動」することがあります。)
  • モジュールのメンテナーが $team_ansible でない場合は、プル要求が community_review 状態になります。
  • モジュールのメンテナーが $team_ansible の場合、プル要求は core_review 状態になります (そして、おそらくしばらくそのままになります)。
  • プル要求が community_review にあり、メンテナーからコメントを受け取った場合は、以下のようになります。
    • メンテナーが shipit と判断すると、プル要求に shipit というラベルが付けられ、Core チームが最終的なマージのためにそれを評価します。
    • メンテナーが needs_info と判断すると、プル要求に needs_info というラベルが付けられ、提出したユーザーに詳細情報の提供が求められます。
    • メンテナーが needs_revision と判断すると、プル要求に needs_revision というラベルが付けられ、提出したユーザーは一部修正を求められます。
  • 提出したユーザーが ready_for_review と判断すると、そのプル要求は community_review または core_review に戻され、プル要求の再レビューの準備ができたことがメンテナーに通知されます。
  • プル要求に needs_revision または needs_info というラベルが付けられ、提出したユーザーが応答しない場合は、以下のようになります。
    • 提出したユーザーは 2 週間後に丁寧な通知を受け取り、さらに 2 週間後に再度連絡が入り、pending action (保留中) というラベルが付けられ、その 2 週間後に問題またはプル要求がクローズになります。
    • 提出したユーザーが応答すると、タイマーがリセットされます。
  • プル要求に community_review というラベルが付けられ、レビュー担当者が応答しない場合は、以下のようになります。
    • レビューアーは 2 週間後に丁寧な通知を受け取り、さらに 2 週間後に再度通知があり、pending_action と表示されます。その後、$team_ansible に再アサインされたり、core_review というラベルが付きます。もしくは、プル要求の提出者がメンテナーとしてステップアップするように要求されます。
  • Shippable テストが失敗したり、コードをマージできないと、プル要求は自動的に needs_revision に置かれ、その理由を説明するメッセージが提出したユーザーに送られます。

めったに発生しない場合や、頻繁に改良される場合がありますが、これは一般的なワークフローです。

プル要求のラベル

一般的に、プル要求には、ワークフロー ラベルおよび 情報 ラベルの 2 つのタイプがあります。

ワークフローラベル
  • community_review: Ansible コミュニティーのメンテナーが確認するのを待っているモジュールのプル要求。
  • core_review: 現在 Ansible Core チームのメンテナーによる確認を待っているモジュールのプル要求。
  • needs_info: 提出したユーザーからの情報を待っています。
  • needs_rebase: 提出したユーザーがリベースを行うのを待っています。
  • needs_revision: 提出したユーザーが変更を行うのを待っています。
  • shipit: マージの可能性があるかどうか、Core チームによる最終レビューを待っています。
情報ラベル
  • backport: これは、devel 以外のブランチに対してプル要求が要求された場合に自動的に適用されます。ボットはすぐに backport と core_review というラベルを割り当てます。
  • bugfix_pull_request: プル要求のテンプレート化された説明に基づいてボットが適用します。
  • cloud: 変更されたファイルのパスに基づいてボットが適用します。
  • docs_pull_request: プル要求のテンプレート化された説明に基づいてボットが適用します。
  • easyfix: 手動で適用され、その使用は一貫性はありまあせんが、場合によっては役に立ちます。
  • feature_pull_request: プル要求のテンプレート化された説明に基づいてボットが適用します。
  • networking: 変更されたファイルのパスに基づいてボットが適用します。
  • owner_pr: 大半が非推奨になりました。以前はワークフローでしたが、現在は情報です。元々、メンテナーから提出されたプル要求は、このラベルに基づいて自動的に shipit に送られていました。提出したユーザーがメンテナーでもある場合、他のメンテナーに通知しても、(提出したユーザーを含む) メンテナーの一人に shipit を提供するように要求するようになりました。
  • pending_action: ボットにより、変化のないプル要求に適用されます。コミュニティーチームが 2、３ 週間ごとにレビューし、適切なアクション (修了、新しいメンテナーの募集など) を考えます。
特殊なラベル
  • new_plugin: これは Ansible にない新しいモジュールやプラグインのためのものです。

注記: new_plugin は完全に別のプロセスを起動しますが、率直に言って現在はあまりうまく機能していません。このプロセスを改善するために最善を尽くしています。

ユーザーによるプル要求のレビュー

Ansibot がプル要求をレビューしてラベルを適用したら、ユーザーがプル要求をレビューする準備が整います。いずれのプル要求でも、それをレビューする可能性が高いのは、プル要求が変更するモジュールのメンテナーです。

各モジュールには少なくとも メンテナー が 1 人割り当てられており、BOTMETA.yml ファイルに記載されています。

メンテナーの仕事は、そのモジュールに影響を与えるプル要求をレビューして、マージ (shipit) すべきか修正 (needs_revision) すべきかを判断することです。すべてのモジュールには少なくともコミュニティーのメンテナーが 1 人必要です。モジュールにコミュニティーメンテナーが割り当てられていないと、メンテナーは $team_ansible として表示されます。

ユーザーが shipit ラベルを適用すると、コミット担当者 は、プル要求がマージする準備ができているかどうかを判断します。shipit ラベルを取得したすべてのプル要求が実際にマージ可能な状態になるわけではありませんが、レビュー担当者が優秀で、コミュニティーのガイドラインが優れていればいるほど、shipit に到達したプル要求がマージ可能な状態になる可能性は高くなります。

プル要求を価値あるものにする

すべてのプル要求をマージするわけではありません。ここでは、プル要求を有益で魅力的で、マージする価値のあるものにするためのヒントをいくつかご紹介します。

Changelog

changelog は、ユーザーや開発者が Ansible の変更情報を確認するのに役に立ちます。Ansible では、リリースごとにフラグメントから changelog を作成します。機能を変更したりバグを修正するプル要求には、changelog のフラグメントを追加する 必要があります。新しいモジュールやプラグインを追加するようなプル要求には、changelog のフラグメントを追加する必要はありません。

メジャーリリースだけでなく、マイナーリリースにも短い概要を示した changelog を作成します。バグ修正をバックポートする場合には、バックポートのプル要求に changelog フラグメントを追加してください。

changelog フラグメントの作成

基本的な changelog フラグメントは changelogs/fragments/ ディレクトリーに置かれた .yaml ファイルです。それぞれのファイルには、bugfixes、major_changes などのキーを持つ yaml ディクショナリーが含まれており、その後にバグ修正または機能の changelog エントリーのリストが続きます。それぞれの changelog エントリーは yaml ファイルが組み込まれている rst です。つまり、特定の構成は、yaml ではなく rst で解釈できるようにエスケープする必要があります (または、yaml と rst の両方にエスケープされていることが望ましい場合は、そのようにします)。各プル要求は、既存のものに追加するのではなく、新しいフラグメントファイルを使用する 必要があります。したがって、変更を加えたプル要求までさかのぼることができます。

changelog エントリーを作成するには、changelogs/fragments/ ディレクトリーに一意な名前で新しいファイルを作成します。ファイル名には、プル要求番号と変更の説明が含まれている必要があります。ファイル拡張子は、.yaml で終わらせる必要があります。たとえば、40696-user-backup-shadow-file.yaml です。

1 つの changelog フラグメントには複数のセクションが含まれる場合がありますが、ほとんどの場合セクションは 1 つしか含まれていません。トップレベルキー (bugfixes、major_changes など) は、リリースノートツールの 設定ファイル で定義されています。有効なセクションとその説明を以下に示します。

major_changes Ansible 自体への大規模な変更。通常、モジュールやプラグインの変更は含まれません。

minor_changes Ansible、モジュール、またはプラグインへの小規模な変更。これには、新機能、モジュールに追加された新しいパラメーター、または既存のパラメーターに対する動作の変更が含まれます。

deprecated_features 非推奨となり、将来のリリースで削除が予定されている機能。

removed_features 以前は非推奨で現在削除されている機能。

bugfixes 問題を解決するための修正。このバグ修正に関連する特定の問題がある場合は、changelog エントリーにリンクを追加してください。

known_issues 現在修正されていない、または修正される予定のない既知の問題。

ほとんどの changelog エントリーは bugfixes または minor_changes になります。特定のモジュールに関連する changelog エントリーを作成する場合は、そのエントリーを - [module name] - で始め、関連する問題が存在する場合はその問題へのリンクを記載します。

以下に例を示します。

bugfixes: - win_updates - fixed issue where running win_updates on async fails without any error

minor_changes: - lineinfile - add warning when using an empty regexp (https://github.com/ansible/ansible/issues/29443)

bugfixes:
  - copy module - The copy module was attempting to change the mode of files for
 remote_src=True even if mode was not set as a parameter.  This failed on
 filesystems which do not have permission bits.

changelog フラグメントの詳細は、2.6 リリースの「changelog ディレクトリー」を参照してください。また、yaml に埋め込む rst のヒントなど、形式に関するドキュメントも、「reno documentation」でご覧になれます。

プル要求用に changelog フラグメントを作成したら、ファイルをコミットし、プル要求に追加します。

マージされたプル要求のバックポート

Ansible のプル要求はすべて、最初に devel ブランチにマージする必要があります。プル要求を受け入れて、devel ブランチにマージした後、以下の手順でプル要求を作成して、変更を以前の安定ブランチにバックポートします。

機能のバックポートは 行いません。

Note

これらの手順は、以下を前提としています。

  • stable-2.9 は、バックポートのターゲットリリースブランチです。
  • https://github.com/ansible/ansible.git は、 upstream という名前の git remote として設定されます。upstream という名前の git remote を使用しない場合は、 それに応じて手順を調整してください。
  • https://github.com/<yourgithubaccount>/ansible.git は、 origin という名前の git remote として設定されます。origin という名前の git remote を使用しない場合は、 それに応じて手順を調整してください。

  1. devel、stable、および feature ブランチを準備します。

    git fetch upstream
git checkout -b backport/2.9/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.9

  2. devel ブランチから関連するコミットの SHA を自身の feature ブランチに選別して、必要に応じてマージの競合を処理します。

    git cherry-pick -x [SHA_FROM_DEVEL]

  3. 変更の changelog フラグメント を追加して、コミットします。

  4. feature ブランチを GitHub のフォークにプッシュします。

    git push origin backport/2.9/[PR_NUMBER_FROM_DEVEL]

  5. stable-2.9 ブランチに対する backport/2.9/[PR_NUMBER_FROM_DEVEL] のプル要求を提出します。

  6. 次のマイナーリリースまでにバックポートのプル要求をマージするかどうかはリリースマネージャーが判断します。フォローアップの必要はありません。自動テスト (CI) に問題が発生していないことを確認するだけです。

Note

backport/2.9/[PR_NUMBER_FROM_DEVEL] を feature ブランチの名前として使用する選択は任意ですが、 そのブランチの目的を伝えています。この形式を使うことは必須ではありませんが、 特に複数の stable ブランチに対して、 複数のバックポートのプル要求を作成する場合に役立ちます。

Note

必要に応じて、 CPython の cherry-picker ツール (pip install --user 'cherry-picker >= 1.3.2') を使用して、 Ansible の devel から stable ブランチへのコミットをバックポートすることができます。インストール、設定、使用方法の詳細は、 「cherry-picker のドキュメント」を参照してください。