aws-cdk-rfcs 読み解き
hassaku63
本家レポジトリでは、P1 ラベルや L2 Construct の仕様変更を要求する改修など、影響が大きいものは RFC を通してから実装せよとある。
In many cases, the GitHub issue is sufficient for such discussions, and can be sufficient to get clarity on what you plan to do. If the changes are significant or intrusive to the existing CDK experience, and especially for a brand new L2 construct implementation, please write an RFC in our RFC repository before jumping into the code base. **L2 construct implementation pull requests will not be reviewed without linking an approved RFC.
L2 Construct の実装は承認された RFC が存在しないとレビューされない。
私が今やろうとしている変更はこの条件に該当するので、RFC の出し方のお作法を確認していく。
hassaku63What is an RFC?
メンテナ、コントリビューター、ユーザーからコメントを要求するもの。
RFC は誰でも作成できる。変更に対するフィードバックを得るために使用できる。
RFC はほとんどの場合メンテナによって作成されるが、コントリビューターによる提案も大関係である。
コントリビューターが RFC を作成したい場合、Slack の #aws-cdk-rfcs でコアチームに連絡して自分の仕事をスポンサーしてくれる人がいるかどうか相談してみると良い。そうでないと、コアチームは手助けできない可能性が高い。
hassaku63RFC Process
issue の起票から始める。issue テンプレートが存在するのでそれを使って、ここに書かれている指示に従う。ここには RFC が通過する必要があるプロセスのチェックリストが含まれている。
1. Tracking issue
RFC と GitHub issue は対応している。issue が会話する場所になる。
issue の番号は RFC の一意な識別子として用いられる。
issue を作成する前に類似の issue が上がっていないかを検索すること。関連する RFC が存在する場合は、現在の段階に基づきその RFC に協力する
issue template には RFC がパスすべきすべての段階におけるチェックリストが含まれている。RFC のプロセス全体を通してチェックリストを更新し、正しいラベルを割り当てる必要がある。これはドライバー(?) の責任である。
2. API Bar Raiser
あなたの RFC に割り当てられた "API Bar Raiser" (とは？) を取得するには、#aws-cdk-rfcs で連絡する必要がある。
※多分 "API Bar Raiser" は特定のロールの名前。
それぞれの RFC について、CDK のリーダーシップメンバーは "API Bar Raiser" を割り当てる。API Bar Riaser は、機能の公開 API をレビューし、承認する。また、命名・構造・オプション・CLI コマンドなど、API に関連する設計に対して拒否権を持っている。
公開 API のデザインは "One way door" であると見做されている。
Bar Raiser は、その機能を利用する可能性があるユーザーの規模に応じて決まる。影響範囲が重大であるほどよりアサインも大きな単位になる。
RFC をマージするには API Bar Raise による承認 (sign-off) が必要になる。そのため、プロセスの早い段階から Sign-off してくれる人と協力して API の設計について調整することが推奨。
↓こんなこと書いてあるがちょっと詳細はイメージできず
NOTE: The technical solution proposed in an RFC does not require approval beyond the normal pull request approval model (e.g. a core team member needs to approve the RFC PR and any subsequent changes to it).
3. Kick-off
RFC 作成に入る前に、 API Bar Raise とこの RFC に興味がある or アイデアを提供できる関係者を含むキックオフミーティングをすることを強く推奨する。
キックオフミーティングの目的は機能とその範囲、実装の一般的な方向性について議論すること。経験上、そうすることで時間とエネルギーを大きく節約できる。
Amazon の CDK チームに属していない場合は、#aws-cdk-rfcs で連絡すれば、ミーティング開催をサポートできる。
会議では、issue を使って初期の API デザインのアイデアを記録する。RFC 自体の準備として初期のフィードバックやユースケースを収集できる。参加者が issue から文脈を把握できるようにする。会議が終了する際に、アイデアや決定事項を issue に記録して、チェックリストを更新しキックオフが開催されたことを示す。
4. RFC Document
0000-template.md のテンプレートに従って、RFC の最初のリビジョンを作成する。
text/NNN-name.md にファイルを作成する。NNNN は issue の番号。
RFC に含めるべき事項はなにか？RFC の目的は曖昧さとリスクを軽減し、機能のリリース後に "One way door" である公開 API の承認を得ることである。あるいは、ドキュメントの目標や内容が、機能や変更のための信頼性の高い実装計画の作成に貢献できる内容になっていること。
多くの場合では、RFC の作成中にプロトタイプを開発したり、実際の開発を開始すると便利。コードは破棄したり大きなリファクタリングを必要とする場合があるが、経験上優れた RFC はより詳細に踏み込んだ内容になっていることが判明している。プロトタイプはデザインが（RFC の文章で表現された方法と比べて）「保たれている」ことを確認できる、優れた方法である。
5. Feedback
RFC の最初のバージョンを PR として提出する。初期のフィードバックを収集するために未完成の RFC を提出することは問題ない。
#aws-cdk-rfcs で CDK コアチームに連絡を取り、Slack のいくつかのチャンネルを通すなどして、できるだけ広くフィードバックを集めること。
おそらく、ここが RFC のプロセスで最も長くなる。また、ほとんどのフィードバックがここで集まる。
早くて 1-2 週間ほどになる。長いと数ヶ月になるものもある。
いくつか tips がある；
- コメントに対応しないで解決するなら、その説明に時間をつかうこと
- 多様な人が来ていることを理解する。コメントがズレているように見えるなら、詳細や例示を尋ねたりする
- あなたの API Bar Raiser と協力すること。意見に相違があるならメンションして意見を求めること
- 忍耐強くあること。RFC が収束するまでに時間が掛かることもある。
- 最初のリビジョンで全部を解決しなければならないわけじゃない。一部の問題を後で解決することもある。それを明記し、合意が取れているならOK。実装中に RFC を何度も更新することはよくある
6. API Sign-off
RFC をマージする前に、API Bar Raiser から公開 API に関して承認を取る必要がある。
通常、これは ”Working backwords" セクションによって説明される。
API Bar Raiser は PR に "api-approved" ラベルをつけることで承認を示す。承認されたら RFC を更新し、チェックリストの該当項目にチェックする。
[x] Signed-off by API Bar Raiser @foobar
7. Final Comments Period
レビュー期間中に提出されたほとんどの問題が合意され、マージする準備が整ったとする。このとき、著者はフィードバックの期限をつけるために "Final comments period" を宣言できる。この宣言は、ここで大きな懸念事項が提案されない限り、RFC は１週間以内に承認され、マージされることを意味する。
関連するステークホルダーに通知するために、RFC がこの段階に入ったことを RFC の PR, issue そして必要があれば Slack やメールにコメントすること。
"Final comments period" が終了したら、コアチームの一員からの承認を求め、PR をマージすることができる。
これで、RFC は「承認」状態に移行する。
8. Implementation
大きな変更の場合、必要なすべてのタスクをリスト化した実装計画を作ることを強く推奨する。
多くの場合、大規模な実装は分割し、複数のイテレーションを通してリリースされるべきである。具体的な計画を立てて作業を分割することは、非常に有益である。
実装計画は RFC の PR に付録として追記し、ステークホルダーの承認を求めるのと一緒に提出するべき。
このプロセス全体を通じて、issue を更新する。
- "implementation lead" のエイリアスを追加する (?)
- 実行計画が提出された (label:
status/planning) - 計画が承認され、マージされた (label:
status/implementing) - 実装が完了した (label:
status/done)
hassaku63State Diagram
RFC プロセスの図。
- Proposed ... issue が作成された。基本的な概要が記載されている。
- Review ... RFC が作成されて、PR としてレビュー中である
- Final Comment Period ... レビュアーが PR を承認し、最終確認期間に入った。大きな問題が生じた場合は "Review" に戻ることがある
- Approved ... PR が承認され、master にマージされ、RFC は実装の準備ができている
- Planning ... RFC の実装計画セクションの PR が作成される
- Done ... 実装が完了し、適切なレポジトリ全体にマージされた
- Rejected ... レビュー期間中に RFC が却下された