変更量の測定¶
多くの場合、変更によってフォーマットやパフォーマンスに影響が出ます。これらの変更を定量化するのは難しいので、それを容易にするためのツールを用意しています。
PRを送信する前に、Blackによるフォーマット変更がもたらす定量化可能な変更を評価することをお勧めします。既に「Blackでフォーマット済み」のプロジェクトに、変更が十分に破壊的であるかどうか、フラストレーションを引き起こす可能性があるかどうかを考えてください。
diff-shades¶
diff-shadesは、オープンソースプロジェクトのリスト全体でBlackを実行し、結果を記録するツールです。diff-shadesの主な特徴は、Blackの2つのリビジョンを比較できることです。これは、特定のPRのマージによって発生する正確な変更を確認できるため、非常に役立ちます。
詳細については、diff-shadesのドキュメントを参照してください。
CI統合¶
diff-shadesは、PRに対する「diff-shadesの結果を比較…」/「diff-shadesは変更を報告しない…」というコメントにも使用されているツールです。このプロジェクトには、これらのルールに従ってBlackの2つのリビジョンを分析して比較するGitHub Actionsワークフローがあります。
ベースラインリビジョン |
ターゲットリビジョン |
|
|---|---|---|
PRの場合 |
|
|
プッシュの場合（mainのみ） |
最新のPyPIバージョン |
プッシュされたコミット |
mainへのプッシュの場合、preview-changesという名前の分析ジョブが1つだけあり、プレビュースタイルがすべてのプロジェクトで使用されます。
PRの場合、もう1つの分析ジョブassert-no-changesが追加されます。preview-changesに似ていますが、安定したコードスタイルで実行されます。変更が行われた場合、失敗します。これにより、Blackの安定性ポリシーに従って、同じ年にコードが何度も再フォーマットされることがなくなります。
さらにPRの場合、プレビュー変更のサマリーと詳細情報のリンクを埋め込んだPRコメントが投稿されます。同じPRでワークフローが次にトリガーされた場合、既存のdiff-shadesコメントがある場合は、代わりに更新されます。
注記
ファイルのフォーマットに失敗した場合、preview-changesジョブは意図的にのみ失敗します。それ以外の失敗は、ワークフローのバグを示しています。
ワークフローは完了時にいくつかのアーティファクトをアップロードします。
生の分析（.json）
HTML diff（.html）
.pr-comment.json（PRによってトリガーされた場合）
最後はdiff-shades-commentワークフローによってダウンロードされ、ローカルでダウンロードする必要はありません。HTML diffは、コメントを投稿するPRがないプッシュベースの場合に役立ちます。分析は、収集したデータをローカルでさらに分析したい場合に備えて存在します。