レビュー

cdg task review はタスクを、cdg dag review はワークフロー全体をレビューします。どちらも、承認、キャンセル、見送りのいずれかの結論を出します。タスクでは、結論を出さずに修正を続けることもできます。それぞれのアクションがどんな判断に向いているか、レビューの前に結果をどう確認するかは、タスクとワークフローをレビューするを参照してください。

アクションと構文

レビューコマンドのアクションは、3 種類に分かれます。accept、cancel、defer は最終アクションで、結論を出し、タスクまたはワークフローは reviewed になります。revise、request-changes、rework は継続アクションで、タスクにだけ使えます。結論は出さず、タスクの修正を続けます。clear は、すでにあるレビュー記録をクリアします。最終アクションと継続アクションの違いは、レビューアクションを参照してください。

cdg task review <アクション> <タスク> [-w <ワークフロー>] [オプション]
cdg dag review <アクション> [<ワークフロー>...] [オプション]
cdg task review clear <タスク> -w <ワークフロー>
cdg dag review clear <ワークフロー>...

タスクレベルの 6 つのアクションは、どれも review を省略できます。たとえば cdg task request-changes 2 -w feature です。ワークフローレベルの 3 つのアクションも、同じように省略形で書けます。たとえば cdg dag accept feature です。2 つの clear には、省略形がありません。

レビューアクションは、投入済みでまだキューにあるワークフローに作用します。タスクレベルのアクションは、そのうちの 1 つのワークフローのタスクを処理します。ワークフローは -w で指定し、省略した場合はキューの先頭のワークフローになります。ワークフローレベルのアクションは、キューの先頭で実行中のワークフローも、後ろに並んでいてまだ開始されていないワークフローも処理できます。まだ投入されていないワークフローに accept、cancel、defer を実行した場合も、コマンドは成功し、結果を記録します。ただし、そのあと cdg dag submit はこのワークフローの投入を拒否するため、先にこれらのレビュー記録をクリアする必要があります。レビュー記録のクリアと再投入を参照してください。

引数とオプション

レビューコマンドの引数は、2 つの部分に分かれます。タスクとワークフローでレビューの対象を指定し、オプションで、コードをどう扱うか、下流をどう扱うか、まだ実行中の対象を先に止めるかどうかを決めます。

タスクとワークフローの一般的な書き方は、1 つまたは複数のタスクを指定する、タスクセレクター、ワークフローを指定するを参照してください。レビューコマンドのセレクターには、制御コマンドと異なる点が 1 つあります。--only を除き、各セレクターに指定できるタスク ID は 1 つだけです。一方、pause や kill などの制御コマンドのセレクターには、複数指定できます。--upto 2 3 と書くと、余分な 3 は直接書いたタスク ID として扱われ、タスク ID とセレクターを同時に使ったことになるため、コマンドはエラーになります。

--code

--code は、タスクが残した変更をレビューのときにどう扱うかを決めます。使えるのは分離ブランチモードだけで、共有ワークスペースモードでこのオプションを書くとエラーになります。ここでいう変更とは、タスクの開始後に生じたすべての変更のことで、ワークスペースにあるまだコミットされていないファイルも、タスクエージェントが自分で行ったコミットも含みます。巻き戻す場合、タスクブランチはタスク開始前のクリーンベースラインに戻り、上流タスクからマージされた結果はそのまま残ります。その意味は、結果に納得できないときの備えを参照してください。

タスクが変更を残していない場合は、どの値を指定しても処理する内容がなく、スナップショットブランチも作られません。スナップショットブランチに何が入っているか、どう見つけて必要な部分を取り出すかは、スナップショットから一部の変更を取り出すを参照してください。アクションごとのデフォルト値と指定できる値は、タスクレベルとワークフローレベルの組み合わせ表を参照してください。

ワークフローレベルのレビューでも、--code を使えます。指定できる値は commit、snapshot、discard で、none はありません。まず、ワークフローの中で実行はされたものの、まだ結論が出ていないタスクを、上の表に従って 1 つずつ処理し、そのあと統合ブランチを処理します。accept では、統合ブランチにマージ済みの結果がそのまま残ります。cancel と defer では、統合ブランチが今回のワークフローのベースに戻ります。このうち snapshot では、先に結果一式がワークフローのスナップショットブランチに保存されます。commit と discard では、結果一式が別に保存されることはありません。まだ実行が始まっていないワークフローには統合ブランチがないため、処理するコードもありません。

--downstream

--downstream は、最終的な結論を出したあと、このタスクに依存する下流のタスク、またはキューでこのワークフローの後ろに並んだワークフローをどう続けるかを決めます。値を選べるのは、cancel と defer だけです。accept は proceed に固定されていて、ほかの値を書くとエラーになります。3 つの継続アクションは、このオプションを受け付けません。

このオプションを書かない場合、defer のデフォルトは cascade です。cancel にはデフォルト値がなく、下流がある場合はコマンドがターミナルで選択を求め、下流がない場合は proceed として処理します。スクリプトやエージェントのシェルツールのような、対話型ターミナルのない環境では、この質問に答えられません。コマンドはエラーを出して終了コード 1 で終了し、何も変更しません。あわせて、--downstream を明記してやり直すよう案内します。保留になった下流が、保留の解除後にどう続行されるかは、下流が保留になったを参照してください。

-m / --message

-m はテキストを添えるオプションで、その用途はアクションによって異なります。最終アクションと revise ではレビューメモとして扱われ、request-changes と rework ではタスクエージェントに渡されます。

継続アクションでも、コミットが作られることがあります。たとえば request-changes は、デフォルトで、先に現在の変更をコミットします。こうしたコミットのメッセージは CodeDAG review <アクション> task <タスク ID> に固定されていて、-m の内容は使われません。修正依頼の内容をわかりやすく書く方法は、今の結果をもとに修正を続けさせるを参照してください。

-k / --kill と -p / --pause

レビューの対象がまだ実行中の場合は、-k または -p で先に止めてから、レビューアクションを実行します。この 2 つのオプションは、タスクレベルの 6 つのアクションとワークフローレベルの 3 つのアクションで使え、一度に書けるのはどちらか一方だけです。対象が実行中でない場合は、何の効果もありません。ワークフローレベルのコマンドに付けた場合は、ワークフロー内の実行中のタスクすべてが対象になります。

• -k、--kill：すぐに強制停止します。効果は cdg task kill または cdg dag kill と同じです。タスクエージェントの手元の作業は中断され、セッションは残ります。残った変更は途中までしか終わっていない可能性があるので、承認またはコミットする前に確認してください。
• -p、--pause：先に一時停止し、タスクエージェントが手元の作業を終えて止まるのを待ってから、レビューを実行します。効果は cdg task pause または cdg dag pause と同じです。コマンドが待つのは、最大 60 秒です。それまでにエージェントが止まらなかった場合、コマンドはエラーで終了し、レビューは実行されません。タスクはドレイン中（draining）のままなので、止まってからもう一度レビューを実行してください。そのときは、-p を付ける必要はありません。

この 2 つのオプションを付けない場合、対象が実行中（working または draining）であれば、accept、defer、3 つの継続アクションは、どれもそのままエラーになり、何も変更しません。cancel は、先に強制停止するか、先に一時停止するか、今回のレビューをやめるかを、ターミナルで選ぶよう求めます。対話型ターミナルがない場合は、エラーを出して終了コード 1 で終了し、-k または -p を明記するよう案内します。人が選択しなくてもキャンセルを完了できるようにするには、止め方と下流の扱いをあわせて明記します。

# 先にタスク 3 を強制停止してからキャンセルする。タスク 3 に依存する下流は通常どおり実行される
cdg task review cancel 3 -w feature -k --downstream proceed
# 先にワークフロー全体を強制停止してからキャンセルする。キューの後ろのワークフローは通常どおり開始される
cdg dag review cancel feature -k --downstream proceed

実行中のタスクに継続アクションを使うときの書き方は、実行中のタスクに request-changes を実行するを参照してください。

アクションとオプションの組み合わせ

タスクレベル

分離ブランチモードでは、タスクレベルの 6 つのアクションごとに、--code と --downstream のデフォルト値と指定できる値が決まっています。継続アクションでは、さらに、タスクがすでに止まっている必要があります。-m は、6 つのアクションのどれでも省略できます。用途は -m / --message を参照してください。共有ワークスペースモードでの違いは、共有ワークスペースモードを参照してください。

最終アクションは、まだ結論が出ていないタスクであれば、どのタスクにも使えます。上流待ちまたは保留のタスク、一時停止または強制停止されたタスク、すでに完了したタスクも含まれます。まだ開始されていないタスクは、キャンセルまたは見送りにすると実行されなくなります。こうしたタスクには変更がないため、--code は効果がありません。タスクが実行中の場合は、-k または -p を付ける必要があります。

開始前の準備に失敗して止まったタスクは、cancel と defer でそのまま終わらせることができます。先に原因に対処したり、cdg task recover を実行したりする必要はありません。こうしたタスクは、on-hold で止まっているか、止まったあとで強制停止されて killed になっています。理由は、たとえばワークスペースがクリーンでない、指定したブランチ名が占有されている、といったものです。こうしたタスクは一度も実行されていないため、レビューはそのワークスペースをチェックせず、そこにある未コミットの変更にも手を付けません。--code は、デフォルト値でも明示的に指定した値でも、こうしたタスクには効果がありません。ただし、タスクが占有しているワークスペースが統合ワークスペースでもある場合（典型的には、ワークスペースが 1 つだけのプロジェクトのプライマリリポジトリ）は、cdg dag review でワークフロー全体を終わらせる前に、そのワークスペースをクリーンにしておく必要があります。accept と 3 つの継続アクションは、こうして止まったタスクに対しては、やはりエラーになります。エラーメッセージには、2 つの対処方法が示されます。原因に対処してから復旧するか、代わりに cancel または defer を使うかです。止まった理由ごとの対処手順は、タスクまたはワークフローが on-hold で止まっているを参照してください。

accept と組み合わせられるのは、commit と proceed だけです。承認された結果は、必ずタスクブランチにコミットされ、下流に渡されるからです。request-changes は、デフォルトで、先に現在の変更をタスクブランチにコミットしてから、依頼をエージェントに渡します。こうしておくと、新しいターンで何が変更されたかを、切り分けて確認できます。

継続アクションを使うには、タスクがすでに止まっている必要があります。done であるか、一時停止（paused）または強制停止（killed）されている状態です。一時停止または強制停止されたタスクに revise を実行すると、タスクは done に戻り、ユーザーが修正を終えて結論を出すのを待ちます。request-changes は、依頼を元のセッションに渡します。エージェントがそのターンを終えると、タスクは再び done に戻り、所属するワークフローのレビュー設定に従って、レビューを待つか、自動承認されます。rework は、新しいセッションに切り替えて、クリーンベースラインからやり直させます。元のセッションはこのタスクから参照されなくなり、それ以降 cdg task view で入るのは新しいセッションです。保留（on-hold）のタスクには、継続アクションを直接は使えません。先に理由に応じて対処してから cdg task recover で復旧するか、最終アクションでタスクを終わらせます。

ワークフローレベル

ワークフローレベルの 3 つのアクションのデフォルト値は、タスクレベルの同名のアクションと同じです。違いは、--code に none がないことと、--downstream がキューの後ろに並んだワークフローに作用することです。-m も、同じように省略できます。

ワークフローレベルのレビューは、ワークフローレベルのゲートまで待たなくても使え、いつでもワークフロー全体に結論を出せます。このとき、すでに結論が出ているタスクは、その結論のままです。実行はされたものの、まだ結論が出ていないタスクには、ワークフローと同じ結論が付き、変更は --code に従って 1 つずつ処理されます。まだ開始されていないタスクは実行されなくなり、レビュー結果も付きません。そのあと、ワークフローは reviewed になり、キューを離れます。後ろに並んでいてまだ開始されていないワークフローに cancel または defer を実行すると、そのワークフローは実行されなくなります。

共有ワークスペースモード

共有ワークスペースモードには、タスクブランチも統合ブランチもありません。レビューで決まるのは実行をどう続けるかだけで、ファイルは処理されません。タスクレベルでは accept、cancel、defer、revise、request-changes を、ワークフローレベルでは accept、cancel、defer を使えます。rework は使えません。また、どのアクションにも --code は付けられず、書くとエラーになります。このエラーの判定で見られるのは、コマンドで直接指定したワークフローだけです。分離ブランチモードのワークフローに対するワークフローレベルのレビューが、--downstream cascade で共有ワークスペースモードのワークフローにカスケードした場合、それらのワークフローは通常どおりそのアクションで終了し、コードの処理が行われないだけです。--downstream、-m、-k、-p の使い方とデフォルト値は変わりません。

タスクが書いたファイルは、すべて、ワークフローが実行されるワークスペースに残ります。デフォルトでは、プライマリリポジトリです。キャンセルまたは見送りにしても、これらのファイルは取り消されず、下流からもそのまま見えます。残す場合も取り消す場合も、そのワークスペースで Git を使って、自分でコミットするか元に戻します。こうした変更をレビューの前に確認する方法は、共有ワークスペースモードでは、レビューはどう変わりますかを参照してください。

場面別の操作例

タスクをキャンセルし、下流は続行させる

タスクをキャンセルするときに --downstream proceed を明記すると、下流はこのタスクを飛ばし、その上流の結果をもとに通常どおり実行されます。次の例では、ワークフロー feature のタスク 2 がタスク 1 に依存し、タスク 4 がタスク 2 に依存します。

# タスク 2 をキャンセルし、変更をスナップショットブランチに保存する。タスク 4 は通常どおり実行される
cdg task review cancel 2 -w feature --downstream proceed
# タスク 2 をキャンセルし、変更をそのまま破棄する。タスク 4 は通常どおり実行される
cdg task review cancel 2 -w feature --downstream proceed --code discard

どちらのコマンドでも、タスク 4 が開始時に受け取るのはタスク 1 の結果で、タスク 2 の変更は含まれません。1 つ目のコマンドで残ったスナップショットブランチからは、あとで変更を取り出せます。スナップショットから一部の変更を取り出すを参照してください。タスク 2 がまだ開始されていない場合も、同じようにキャンセルでき、その場合、タスク 2 は実行されません。実行中の場合は、-k を付けます。

結果の採用を見送り、あとで取り出せるようにコードを残す

defer は、このステップを今回は採用しないことを表します。もともとデフォルトで --code snapshot が使われ、変更はスナップショットブランチに保存されます。次のコマンドでは、意図がはっきりするように、これを明示的に書いています。

# タスク 2 を見送り、変更をスナップショットブランチに保存する。タスク 2 に依存する下流もまとめて見送られる
cdg task review defer 2 -w feature --code snapshot
# タスク 2 だけを見送る。タスク 2 に依存する下流は通常どおり実行される
cdg task review defer 2 -w feature --code snapshot --downstream proceed
# ワークフロー全体を見送り、結果一式をワークフローのスナップショットブランチに保存する。キューの後ろのワークフローは通常どおり開始される
cdg dag review defer feature --code snapshot --downstream proceed

タスクレベルでもワークフローレベルでも、defer はデフォルトでカスケードします。下流の範囲は --downstream を参照してください。スナップショットブランチから変更を取り出す方法は、スナップショットから一部の変更を取り出すを参照してください。見送った部分をあとで進めるときは、新しいワークフローに書きます。一部のタスクだけをあとから実行するを参照してください。

実行中のタスクに request-changes を実行する

タスクがまだ実行中でも、-k または -p を付けて先に止めれば、request-changes で新しい依頼を元のセッションに渡せます。対話型ターミナルは必要ありません。

# タスク 2 をすぐに強制停止してから、修正依頼の内容を元のセッションに渡す
cdg task review request-changes 2 -w feature -k -m "<修正依頼の内容>"
# タスク 2 が手元の作業を終えて止まるのを待ってから、修正依頼の内容を渡す
cdg task review request-changes 2 -w feature -p -m "<修正依頼の内容>"

-m を省略した場合は、組み込みの依頼文が送られます。2 つの止め方の違いは -k と -p を参照してください。修正を始める前に、デフォルトで、先に現在の変更がコミットされます。デフォルト値と指定できる値は、タスクレベルの組み合わせ表を参照してください。この方法と、セッションに入って直接やり取りする方法をどう使い分けるかは、監視と修正の方法を選ぶを参照してください。

-k を付けた場合、コマンドは少しの間待って、修正依頼の内容がセッションに届いたことを確認します。届いたことを確認できて初めて、コマンドは終了します。待ち時間が過ぎてもまだ確認中の場合は、コマンドが先に終了し、送信はバックグラウンドで続けられます。最終的に依頼が届かなかった場合、タスクは on-hold で止まり、理由は continuation-dispatch-failed になります。cdg task recover 2 -w feature を実行すると、同じ依頼がもう一度送られます。

修正依頼の内容が届くまで、このタスクは新しいレビューコマンドを受け付けません。CodeDAG がこのタスクを復旧している最中も同じで、コマンドは、すでに処理が進行中であることを知らせます。その処理が終わってから、レビューしてください。タスクが on-hold で止まっている場合は、先に cdg task recover を実行します。

複数のタスクをまとめてレビューする

1 つのレビューコマンドで、同じワークフローの複数のタスクを処理できます。それらのタスクには、同じアクションと同じオプションが適用されます。タスク ID を複数並べて書くことも、タスクセレクターを使って依存関係をもとに選ぶこともできます。

# タスク 2 とタスク 3 を承認する
cdg task accept 2 3 -w feature
# タスク 4 と、タスク 4 に依存するすべてのタスクを見送る
cdg task defer --downfrom 4 -w feature

セレクターは依存関係だけをもとにタスクを選び、タスクの状態は見ません。また、最終アクションは、まだ開始されていないタスクにも作用します。そのため、--upto や --downfrom のような範囲を選ぶセレクターを accept と組み合わせた場合、選ばれた中にまだ開始されていないタスクがあると、コマンドはまずそれらを一覧表示し、実行せずに承認するかどうかを尋ねます。デフォルトでは承認しません。-y を付けると、そのまま承認します。対話型ターミナルがなく、-y も付けていない場合は、エラーを出して終了コード 1 で終了します。タスク ID を直接書いた場合や、--only で 1 つずつ指定した場合は、この質問は表示されません。セレクターの書き方の詳細は、タスクセレクターを参照してください。

選んだタスクの中にすでに結論が出ているものがある場合、コマンドはそれらをスキップし、残りのタスクの処理を続けるかどうかを先に尋ねます。対話型ターミナルがない場合は、エラーを出して終了コード 1 で終了します。-y を付けると、そのまま残りのタスクを処理します。

ワークフローレベルのコマンドにも、一度に複数のワークフローを指定できます。たとえば cdg dag review accept feature docs です。これらのワークフローにも、同じアクションと同じオプションが適用されます。そのうち、すでにレビューが終了しているワークフローは、上と同じルールでスキップされ、同じように尋ねられます。cascade を選んだ場合は、指定したワークフローのうちキューでいちばん前にあるものより後ろのワークフローすべてに、まとめて結論が付きます。

レビュー記録のクリアと再投入

レビューが終了したワークフローをもう一度実行するには、ワークフロー全体を単位にするしかありません。まず cdg dag review clear でレビュー記録をクリアして planning に戻し、それから cdg dag submit で投入します。どちらのコマンドでも、ワークフローを明記する必要があります。

cdg dag review clear feature
cdg dag submit feature

cdg dag review clear には、一度に複数のワークフローを指定できます。このコマンドは、ワークフローと、その中のすべてのタスクのレビュー記録をクリアします。タスクブランチ、統合ブランチ、スナップショットブランチはどれもリポジトリに残り、影響を受けません。まだキューにあるワークフローは、スキップされます。一度に指定した複数のワークフローの中にこうしたワークフローがある場合、コマンドは、残りのワークフローのクリアを続けるかどうかを先に尋ねます。対話型ターミナルがない場合は、エラーを出して終了コード 1 で終了します。-y を付けると、そのまま続けます。まだ終了していないワークフローをもう一度実行したい場合は、先に cdg dag review accept、cancel、defer のいずれかで今回の実行を終わらせてから、クリアします。手順の全体は、投入済みのワークフローを変更するを参照してください。

再投入は新しい実行になり、実行が始まるときに、タスク数の分の CodeDAG クレジットが改めて消費されます。新しい実行がどこから始まるか、ブランチにどんな名前が付くかは、もう一度実行するを参照してください。まだ済んでいないタスクを実行したいだけの場合や、一部のタスクだけをやり直したい場合は、一部のタスクだけをあとから実行するを参照してください。

個別のタスクのレビュー記録をクリアする

cdg task review clear <タスク> -w <ワークフロー>

cdg task review clear は、選んだタスクのレビュー記録だけをクリアします。タスクは planning に戻りますが、再実行はされません。レビューが終了したワークフローに対して実行しても、ワークフローを再投入できるようにはならず、ワークフローは reviewed のままです。コマンドの出力にはこの点が明記され、先に cdg dag review clear、続いて cdg dag submit を実行するよう案内されます。つまり、上の方法でワークフロー全体をクリアするということです。そのため、このコマンドは、特定のタスクだけを再実行する目的には使えません。

このコマンドが処理するのは、キューにないワークフローだけです。-w にはデフォルト値がなく、必ず明記する必要があります。省略すると、コマンドは Missing required option '--workflow-file/--dag/-w' というエラーを出し、どのワークフローも読み取らず、変更もしません。選んだタスクのうち、まだ結論が出ていないものはスキップされます。タスクの書き方はほかのレビューコマンドと同じで、--only を除き、セレクターに指定できるタスク ID は 1 つだけです。

まだ投入していないワークフローにあるタスクのレビュー記録

まだ投入していないワークフローのタスクを、cdg task review の accept、cancel、defer でレビューしたあとは、レビュー済みのタスクが 1 つでも残っているかぎり、cdg dag submit はこのワークフローの投入を拒否します。エラーメッセージには、Workflow has review snapshot state と書かれています。投入するには、先にこれらのタスクのレビュー記録をクリアします。クリアには、次の 2 つのコマンドのどちらも使えます。

• cdg dag review clear <ワークフロー>：このワークフローのすべてのタスクのレビュー記録をクリアします。そのあとは、そのまま投入できます。
• cdg task review clear <タスク> -w <ワークフロー>：選んだタスクのレビュー記録をクリアします。クリアした結果、ワークフローにレビュー済みのタスクがなくなれば、ワークフローを投入できます。レビュー済みのタスクがほかに残っている場合は、まだ投入できません。コマンドの出力にはそれらのタスクが一覧表示され、cdg dag review clear <ワークフロー> ですべてのタスクのレビュー記録をクリアするよう案内されます。

関連ページ

• タスクとワークフローをレビューする：6 つのアクションがそれぞれどんな判断に向いているか、レビューの前に結果をどう確認するか。
• 仕上げ、マージ、クリーンアップ：ワークフローのレビューが終了したあとに、統合ブランチを確認し、メインブランチにマージし、もう一度実行する方法。
• 自動承認に指定できる値：どのタスクとワークフローを止めてレビューを待たせるかを、ワークフローファイルで決める方法。