bencher runでのブランチ & スタートポイント
ブランチはgitの参照（例えば、ブランチ名やタグ）です。
bencher run CLIサブコマンドを使用する際は、
--branchオプションまたはBENCHER_BRANCH環境変数を使用してブランチを選択します。
現在のgitハッシュも、--hashオプションで指定できます。
ブランチが指定されていない場合は、利用可能であれば現在のgitブランチ名が使用されます。
それ以外の場合、デフォルトのブランチとしてmainが使用されます。
同様に、gitハッシュが指定されていない場合、利用可能であれば現在のgitハッシュが使用されます。
継続的ベンチマーク、つまりCIでのベンチマークを行う際には、
既存のブランチに新たにブランチを作成するか、またはそのブランチにリベースしたいことが多いです。
これをブランチの開始ポイントと呼びます。
開始ポイントは、特定のバージョン（および利用可能であればgitハッシュ）の他のブランチです。
bencher run CLIサブコマンドを使用する場合、
--start-pointオプションで開始ポイントを選択します。
さらに、--start-point-hashオプションを使用して、開始ポイントの特定のgitハッシュを指定します。
開始ポイントからコピーされるデータ量は、--start-point-max-versionsオプションで制御されます。
同様に、しきい値を--start-point-clone-thresholdsフラグで開始ポイントからコピーできます。
ドリフトを防ぐために、--start-point-resetフラグを使用してブランチを常に開始ポイントにリセットします。
--branch <BRANCH>
Branchを選択するには、--branch オプションまたは BENCHER_BRANCH 環境変数を、Branchの名前、スラッグ、またはUUIDに設定します。
指定された値が名前またはスラッグであり、Branchが既に存在しない場合、自動的に作成されます。
一方、指定された値がUUIDの場合はそのBranchが既に存在している必要があります。
両方が指定された場合、--branch オプションが BENCHER_BRANCH 環境変数より優先されます。
どちらも指定されていない場合、Bencher CLIは現在の git ブランチを探します。
まず、現在の作業ディレクトリ内で git リポジトリを探します。
見つからない場合は、親ディレクトリに進み、ルートディレクトリまで再試行します。
git リポジトリが見つかった場合は、現在の短縮ブランチ名が使用されます。
しかし、git リポジトリが見つからない場合は、main がデフォルトのBranchとして使用されます。
--hash <HASH>
40文字のSHA-1コミットハッシュ。 2つのレポートが同じブランチとハッシュを持っている場合、それらは同じコミットから来たものと見なされます。 したがって、それらは同じブランチバージョン番号を持つでしょう。
提供されない場合、Bencher CLIは現在のgitハッシュを見つけようとします。 最初に、現在の作業ディレクトリでgitリポジトリを探します。 見つからない場合、親ディレクトリに移動してルートディレクトリまで再試行を続けます。 gitリポジトリが見つかった場合、現在のブランチのHEAD gitハッシュが使用されます。
--start-point <BRANCH>
指定されたブランチ名、スラッグ、またはUUIDを開始ポイントとしてブランチオプションで使用します。
GitHubでは通常、プルリクエストのbaseブランチとして使用され、
GitLabでは通常、マージリクエストのtargetブランチとして使用されます。
--start-pointの主な使用ケースは統計的継続ベンチマーキングです。
- 指定された開始ポイントが空文字列の場合、このオプションは無視されます。
branchが存在しない場合、この開始ポイントを使用して作成されます。branchが存在し、開始ポイントが同じ場合、このオプションは無視されます。branchが存在し、開始ポイントが異なる場合、 更新された開始ポイントを使用して新しいbranchヘッドが作成されます。branchが存在せず、開始ポイントが存在しない場合、branchは履歴データなしで作成されます。branchが存在し、開始ポイントが存在しない場合、 このオプションは無視されます。
新しいbranchが開始ポイントと共に作成される場合、
指定された開始ポイントからの最新のデータとオプションでしきい値がコピーされます。
詳細は–start-point-max-versionsオプションおよび–start-point-clone-thresholdsオプションを参照してください。
例えば、feature_branchがまだ存在していないが、mainが存在し履歴データを持っている場合。
--branch feature_branch --start-point mainを使用すると、以下のことが行われます：
feature_branchという名前の新しいブランチを作成するmainからfeature_branchに最新のデータをコピーするbencher runはfeature_branchを使用して続行する
🐰 注: 環境変数を使用する際は、必ずダブルクォーテーションで囲むべきです（例:
--start-point "$MY_BRANCH_ENV_VAR"）。MY_BRANCH_ENV_VARが未定義であってもbencher runがエラーとなることを避けたい場合。
--start-point-hash <HASH>
指定された完全なGitハッシュをbranchオプションのためのスタートポイントとして使用します。このオプションは --start-pointオプションが設定されていることを必要とします。
branchが存在しない場合は、指定されたハッシュでstart-pointから作成されます。branchが存在し、start-pointと指定されたハッシュが同じ場合、このオプションは無視されます。branchが存在し、start-pointまたは指定されたハッシュが異なる場合、新しいbranchHeadが指定されたハッシュでstart-pointから作成されます。branchが存在せず、指定されたハッシュでstart-pointが存在しない場合、branchはstart-pointの最新バージョンから作成されます。start-pointが存在しない場合、branchは履歴データなしで作成されます。branchが存在し、指定されたハッシュでstart-pointが存在しない場合、新しいbranchHeadがstart-pointの最新バージョンから作成されます。start-pointが存在しない場合、このオプションは無視されます。
スタートポイントで新しいbranchが作成された場合、指定されたハッシュでstart-pointからの最新データおよび任意でスレッショルドもコピーされます。詳細は--start-point-max-versionsオプションおよび--start-point-clone-thresholdsオプションを参照してください。
例えば、feature_branchがそのスタートポイントをmainブランチのハッシュ32aea434d751648726097ed3ac760b57107edd8bとして存在している場合、--branch feature_branch --start-point main --start-point-hash 68b12758509ca5e2b1e3983525625e532eb5f562を使用すると:
- 古い
feature_branchHeadが削除されます。 - 新しい
feature_branchHeadが作成されます。 mainのハッシュ68b12758509ca5e2b1e3983525625e532eb5f562からの最新データが新しいfeature_branchHeadにコピーされます。- その後、
bencher runは新しいfeature_branchHeadを使用して進行します。
--start-point-max-versions <COUNT>
指定された最大数の履歴ブランチバージョンをbranch オプションの開始ポイントから含めるようにします。
この数を超えるバージョンは省略されます。
デフォルトは64バージョンです。
このオプションを使用するには、--start-point オプションを設定する必要があります。
例えば、feature_branchが存在し、その開始ポイントがmainブランチであり、
mainが300バージョンある場合、
--branch feature_branch --start-point main --start-point-max-versions 100を使用すると、
mainの最新の100バージョンのみがfeature_branchに含まれます。
--start-point-clone-thresholds
branchオプションのためにStart PointからすべてのThresholdsをクローンします。このフラグを使用するには、--start-point optionを設定する必要があります。
- Thresholdが存在しない場合、
start-pointThresholdから作成されます。 - Thresholdが存在し、かつ
start-pointThresholdと同じである場合、そのThresholdは事実上無視されます。 - Thresholdが存在し、そのモデルが
start-pointThresholdと異なる場合、古いモデルはstart-pointThresholdモデルで置き換えられます。 - Thresholdが存在し、
start-pointThresholdが存在しない場合、そのThresholdモデルは削除されます。
例えば、feature_branchが存在し、そのStart Pointがmainブランチであり、mainには組み込みのlocalhost Testbedとlatency MeasureのためのThresholdが存在する場合、--branch feature_branch --start-point main --start-point-clone-thresholdsを使用すると、localhost Testbedとlatency Measureを持つ新しいThresholdがfeature_branchに作成されます。
--start-point-reset
指定された branch をリセットします。
--start-point オプションが設定されている場合、
branch は指定されたスタートポイントにリセットされます。
これは統計的継続的ベンチマーキングデータのドリフトを防ぐのに役立ちます。
スタートポイントを指定しない --start-point-reset の主な使用ケースは相対的継続的ベンチマーキングです。
branchが存在せず、スタートポイントが指定されていない場合、branchは履歴データなしで作成されます。branchが存在し、スタートポイントが指定されていない場合、 新しいbranchHead が履歴データなしで作成されます。branchが存在せず、スタートポイントが指定されている場合、 スタートポイントを使用してbranchが作成されます。branchが存在し、スタートポイントが指定されている場合、 スタートポイントを使用して新しいbranchHead が作成されます。
スタートポイントで新しい branch が作成された場合、
指定されたハッシュで start-point から最新のデータとオプションでしきい値がコピーされます。
詳細は --start-point-max-versions オプションと --start-point-clone-thresholds オプションを参照してください。
同じ冪等性キーを持つ同じ branch のリセットは1つの branch Head を共有するため、
CI 実行の並列ジョブが互いに branch をリセットし合うことはありません。
GitHub Actions で実行する場合、キーは現在のワークフロー実行の試行に自動的に設定されます。
同じワークフロー実行の後続のステップで branch をリセットする場合も同じ Head が使用されるため、branch を再びリセットする必要があるステップには別のキーを設定してください。
例えば、feature_branch がスタートポイントなしで存在している場合に、
--branch feature_branch --start-point-reset を使用すると：
- 古い
feature_branchHead を削除します - 履歴データなしで新しい
feature_branchHead を作成します bencher runが新しいfeature_branchHead を使用して続行されます
--start-point-idempotency-key <KEY>
指定されたキーを--start-point-reset フラグの冪等性キーとして使用します。
キーには任意のテキストを使用できます。
--start-point-idempotency-key オプションまたは BENCHER_START_POINT_IDEMPOTENCY_KEY 環境変数のいずれかを設定してください。
--start-point-reset が設定されていない場合、またはキーが空の場合、このオプションは無視されます。
- キーを持つ
branchHead がない場合、リセットによってキーを持つ新しいbranchHead が作成されます。 - キーを持つ
branchHead がすでにある場合、その Head が使用され、branchは再びリセットされません。 これは、スタートポイントが変更された場合や、その Head がその後置き換えられた場合でも同様です。
GitHub Actions で実行する場合、キーのデフォルトは現在のワークフロー実行の試行です。
ワークフロー実行のすべてのジョブは1つの branch Head を共有し、ワークフローを再実行すると新しい Head が作成されます。
同じワークフロー実行の後続のステップで branch をリセットする場合も同じ Head が使用されるため、branch を再びリセットする必要があるステップには別のキーを設定してください。
その他の CI プロバイダーでは、パイプライン実行のすべてのジョブで同じになる値をキーに設定してください。
(例: GitLab CI/CD では --start-point-idempotency-key "$CI_PIPELINE_ID")
例えば、ワークフローがそれぞれ --branch feature_branch --start-point main --start-point-reset --start-point-idempotency-key run-abc123 を使用する3つのジョブのマトリックスを実行する場合：
- 最初にレポートしたジョブが
mainから冪等性キーrun-abc123を持つ新しいfeature_branchHead を作成します - その Head が冪等性キー
run-abc123を持つため、残りの2つのジョブは同じfeature_branchHead を使用します - 3つのジョブすべての結果が
feature_branchにまとめて表示されます
🐰 おめでとうございます！ブランチ & スタートポイントに関するすべてを学びました！🎉