🦔

Lambda Powertoolsコントリビュートへの道：CONTRIBUTING.md読解編

2025/05/09に公開

 はじめに以下に記載したようにgithubからコントリビュートを誘われている。
なんかかっこいいのでやってみたいと思う。

 プロジェクトの選択選択するプロジェクトとして「実際に使っているものが良い」ということなので、仕事で使っているlambda power toolsで気になるところがあるので対応してみたいと思う。

 プロジェクトについて学ぶまずはpowertools-lambda-pythonのコントリビュートのお作法を勉強。

 CONTRIBUTING.md
 目次コントリビュートガイドライン
バグや機能リクエストの送信
プルリクエストによるコントリビュート
開発環境の構築
localでドキュメントを見る

慣例
一般的な用語と実践
テストの定義

取り掛かるコントリビューションを探す
行動規範
セキュリティ問題の通知
トラブルシューティング
APIリファレンス

ライセンス


 コントリビュートガイドライン我々のプロジェクトへのコントリビュートに興味を持ってくれてありがとう！

バグレポートでも新機能でも修正でもドキュメントの追加でも、我々はコミュニティからのフィードバックとコントリビューションを高く評価しています！
issueやpull requestを出す前にこのドキュメントを読んでください。それによって我々はあなたへの返信をするための十分な情報を得ることができます。

 バグや機能リクエストの送信バグレポート、機能提案、ドキュメントの改善のためにGitHubのissue trackerを使うことを歓迎します。
issueを書くときは、オープンissue、クローズissueの両方を確認してください。レポートにはできるだけ多くの情報を含めるようにしてください。

 Pull Requestによるコントリビュートpull requestによるコントリビュートは大変歓迎しています。pull requestを出す前に以下を確認してください。

developブランチの最新のソースで作業していること。
その課題に取り組んでいる人がいないことを確認するため、オープンissue、最近マージされたpull requestを確認すること。
実装を始める前にissueを上げてください。優先度付けされていないissueは失敗に終わるかもしれません。
大まかに言うとレポジトリにマージされるステップは以下です。全てのステップは自動化される予定です。

 開発環境の構築最初にレポジトリをforkしましょう。
開発環境を構築するに当たり、我々の設定済みクラウド環境を使うことをおすすめします。https://gitpod.io/#https://github.com/YOUR_USERNAME/aws-lambda-powertools-python

YOUR_USERNAME をあなたのユーザ名や組織に変更しましょう。クラウド環境は先程のforkをターゲットにできます。

それか、ローカル環境用にmake devコマンドを使うこともできます。
pull requestを送る時には次のステップに従ってください。
コントリビュート対象の変更専用のブランチを作成してください

make prで全てのテストとベースラインチェックをしてください

Gitフックはlintingやformattingを行い、make prはCI processでも動作する詳細な確認を実施します。
明確なコミットメッセージを使ってコミットします

conventional semantic titleでpull requestを送り、pull reqest作成時のデフォルトの質問に回答します。
自動化されたCIの失敗報告に注意をはらい、会話を続けてください。
GitHubの以下のドキュメントも参考にしてください。forking a repository、creating a pull request

 localでドキュメントを見る以下のコマンドでドキュメントを見られます。
API reference: make docs-api-local
Docs website: make docs-local
ドッカーがお好みなら: make docs-local-docker


 慣例一般的な用語と実践の一覧が以下です。


カテゴリ
慣例


Docstring
より読みやすいAPIリファレンス生成を促進するため、マークダウンを使ったNumpyの慣習を少し変更した物を使います。

Style guide

PEP8の慣例を超える良い慣習を強制するため、blackとRuffを使います。型アノテーションを使い、mypyによる静的型チェックも行います。

Core utilities
コアユーティリティはクラスを使っており、コンソトラクタのパラメータとして常にserviceを受け付けます。これにより独立して動作可能となり、その他の言語の実装でも利用可能になります。

Utilities
ユーティリティはコアほど厳密ではなくTenetsに従う範囲で開発者の経験を解決するのに集中します。

Exceptions
特定の例外はユーティリティ内に定義されており、MetricUnitError のように Error という接尾辞を付けています。

Git commits

conventional commitsに従います。参入障壁を下げるためにコミット関連を強制はしません。そのかわりにプルリクエストのタイトルは矯正しています。それによりラベルやチェンジログが自動化されます。

API documentation
APIリファレンスのドキュメントはdocstringsから自動生成されていて、IDEで必要なものがわかるように例が掲載される必要があります。ドキュメントのウェブサイトでは、より広範な利用方法やtipsをカバーするため、簡潔にするように努めています。

Documentation
ドキュメントを製品として扱います。入門向けの80%と高度な使用法に20%を咲きます。ユーザが機能を使う時に単体テストの方法を知ることができるようにしています。


 テストの定義テストをカテゴリごとにグループ定義しています。


Test
When to write
Notes
Speed


Unit tests
最も小さい単位での動作確認をします.
ネットワークアクセスは禁止します. 複雑性を考慮すると機能テストで実施するのが良いです.
超高速(nsec から ms)

Functional tests
機能が期待通りに動作することを保証します. 複数のユニットをまたぐ、統合テストのサブセットです.
外部依存はなし、MockやStubを使った実装よりもインメモリのFakeを推奨します.
高速 (ms から 遅くても数秒)

Integration tests
外部依存を持った状態でコードが問題なく動くことを確認する.
lambda関数は不要です。SSMパラメータを取得するなど外部依存に対して我々のコードを使ってください.
遅め (2,3分)

End-to-end tests
lambda関数が期待通りに動作することを確認します.
ソース設定やIAM権限なども含めた、ユーザのlambda関数の設定、デプロイ、実行をシミュレートします.
遅い (数分)

Performance tests
lambda関数のレイテンシーやコストが高まらないことを確認します.
CIのHWに依存して結果が不安定になることがあります. IntegrationテストとEnd-to-endテストのカバレッジが十分になったらPerformanceテストを再開します.
速い~中程度 (数秒から2,3分)

NOTE: Functional tests は必須です。テストを作成するガイドを作成する予定です。メンテナーは追加のテストが必要な場合はそれを伝え、必要な場合は援助してくれます.
コントリビュートする対象を探す。既存のissueを見てみるのは良い方法です。本プロジェクトはデフォルトのGitHub issue labels(enhancement/bug/help wanted/invalid/question/documentation)を採用していますので、'help wanted'を見てみるのはとてもいい案です.
行動規範としてAmazon Open Source Code of Conductを採用しています. より詳しい情報は「Code of Conduct FAQ」を見るか、opensource-codeofconduct@amazon.com までお問い合わせ、コメントをお願いします.
セキュリティ通知。

セキュリティ上の問題を見つけたときは我々の脆弱性レポートページから「AWS/Amazon Security」にお知らせください。github issueには掲載しないでください。
トラブルシューティング：APIリファレンスドキュメント

ローカルのAPIリファレンスドキュメントで変更をプレビューしようとした際に、以下のようなエラーが表示されることがあります

Module aws_lambda_powertools not found
その場合は以下の対策を検討してください。
ローカル開発環境をまだセットアップしていない

→ make dev コマンドで開発用依存関係をインストールする必要があります。
リポジトリ内のコードに例外があり、pdoc のコード解析中に例外が発生している

→ この場合、エラーメッセージは通常表示されません。

poetry run pdoc --pdf aws_lambda_powertoolsによってエラーが表示されるので対処してください

 まとめ以上！

power-toolsのCONTRIBUTING.mdを読み終わりました。

結構やることが多そうですが、千里の道も一歩からですね。
次は環境構築してみたいとおもいます。

カテゴリ	慣例
Docstring	より読みやすいAPIリファレンス生成を促進するため、マークダウンを使ったNumpyの慣習を少し変更した物を使います。
Style guide	PEP8の慣例を超える良い慣習を強制するため、blackとRuffを使います。型アノテーションを使い、mypyによる静的型チェックも行います。
Core utilities	コアユーティリティはクラスを使っており、コンソトラクタのパラメータとして常にserviceを受け付けます。これにより独立して動作可能となり、その他の言語の実装でも利用可能になります。
Utilities	ユーティリティはコアほど厳密ではなくTenetsに従う範囲で開発者の経験を解決するのに集中します。
Exceptions	特定の例外はユーティリティ内に定義されており、MetricUnitError のように Error という接尾辞を付けています。
Git commits	conventional commitsに従います。参入障壁を下げるためにコミット関連を強制はしません。そのかわりにプルリクエストのタイトルは矯正しています。それによりラベルやチェンジログが自動化されます。
API documentation	APIリファレンスのドキュメントはdocstringsから自動生成されていて、IDEで必要なものがわかるように例が掲載される必要があります。ドキュメントのウェブサイトでは、より広範な利用方法やtipsをカバーするため、簡潔にするように努めています。
Documentation	ドキュメントを製品として扱います。入門向けの80%と高度な使用法に20%を咲きます。ユーザが機能を使う時に単体テストの方法を知ることができるようにしています。

Test	When to write	Notes	Speed
Unit tests	最も小さい単位での動作確認をします.	ネットワークアクセスは禁止します. 複雑性を考慮すると機能テストで実施するのが良いです.	超高速(nsec から ms)
Functional tests	機能が期待通りに動作することを保証します. 複数のユニットをまたぐ、統合テストのサブセットです.	外部依存はなし、MockやStubを使った実装よりもインメモリのFakeを推奨します.	高速 (ms から遅くても数秒)
Integration tests	外部依存を持った状態でコードが問題なく動くことを確認する.	lambda関数は不要です。SSMパラメータを取得するなど外部依存に対して我々のコードを使ってください.	遅め (2,3分)
End-to-end tests	lambda関数が期待通りに動作することを確認します.	ソース設定やIAM権限なども含めた、ユーザのlambda関数の設定、デプロイ、実行をシミュレートします.	遅い (数分)
Performance tests	lambda関数のレイテンシーやコストが高まらないことを確認します.	CIのHWに依存して結果が不安定になることがあります. IntegrationテストとEnd-to-endテストのカバレッジが十分になったらPerformanceテストを再開します.	速い~中程度 (数秒から2,3分)

はじめに

プロジェクトの選択

プロジェクトについて学ぶ

CONTRIBUTING.md

目次

コントリビュートガイドライン

バグや機能リクエストの送信

Pull Requestによるコントリビュート

開発環境の構築

localでドキュメントを見る

慣例

テストの定義

まとめ

Discussion