release-notes-generator

リリースノートジェネレーター

Datex Studio の 2 つのブランチ間のリリースノートを、コミット（何がマージされたか）、作業項目（その理由）、設定の差分（実際に何が変更されたか）の 3 つの情報源を組み合わせて生成します。Technical 版と Customer 版の両方を作成します。

参考資料

• ../datex-studio-shared/branch-setup.md — ユーザーがまだ両方のブランチ ID を指定していない場合のブランチ選択
• ../commit-release-notes/SKILL.md — コミットごとのエンジニアリングノートの取得。検証済みの読み取り範囲と JSON/YAML の忠実性について説明しています

前提条件

• --from ブランチ ID — ルートアプリケーションの古いリリース（ベースライン）
• --to ブランチ ID — ルートアプリケーションの新しいリリース（対象）
• dxs ≥ 0.4.9 — source release-tree と組織をまたぐ依存関係の解決が必要です。これより古いビルドでは、deps-diff／compare が依存関係の変更を常に ゼロ と報告します（AppConfig ペイロードから削除されたフィールドを比較していたため）。また、顧客アプリ独自の組織にあるパッケージも解決できません。dxs source release-notes の依存関係セクションにも同じ見落としがあり、0.5.5 まで修正されていませんでした。source deps --tree と source graph も同様に空のツリーを返していました。dxs source release-tree --help が失敗した場合は、そこで停止してその旨を伝えてください。見落としのある方法に切り替えてはいけません。
• dxs ≥ 0.4.24 を強く推奨します。 このビルド以降、release-tree は Service-Pack で固定された依存関係を自動で解決し、サブツリーを黙って削除する代わりに、スキップされたサブツリー（subtree_skipped／summary.subtrees_skipped）を報告し、どちらの側で失敗したか（resolve_failed_sides）を示し、別の組織のリポジトリをインデックス化するための --extra-org を受け付けます。これより古いビルドでは、これらすべてを手動で行う必要があります。Phase 1b を参照してください。
• dxs source release-notes を直接呼び出す場合は dxs ≥ 0.5.4 が必要です（このスキル自体は release-tree を使用しており、影響を受けたことはありません）。依存関係の差分では、両側の marketPlaceApplicationVersionId を比較していました。このフィールドは AppConfig の移行で削除されているため、None と None の比較になり、依存関係の バージョン更新が更新済みとして報告されませんでした。0.5.4 以降は、source compare と deps-diff が使用するのと同じヘルパーを使い、解決済みの version に基づいて差分を取ります。そのため、3 つの機能で結果が一致し、ブランチを解決できないバージョン更新は削除されず、分類不能として報告されます。

両方のブランチ ID を最初に確認する必要があります。ユーザーがブランチ ID ではなく バージョン名（または日付、あるいは片方だけ）を指定した場合は、まずそれを解決してください。詳しくは、以下の「ルートアプリとバージョンの解決」を参照してください。Branch ID Policy が適用されます。ID を決して推測してはいけません。

ルートアプリとバージョンの解決

「ルートアプリケーション」とは、ユーザーがリリースするものです。必ずしもDatex製品とは限りません。顧客がデプロイしたアプリ（例：TobinのFootprint、tob-footprint）は通常、薄い集約アプリです。独自の直接コミットはほとんどないか、まったくなく、そのリリースは依存関係のバージョン更新そのものです。これは想定どおりです。実質的な内容は依存関係にあり、release-treeがそれらを列挙します。

Phase 1の前に、次の2つの解決上の注意点に対応してください。

• 組織をまたぐパッケージ。 顧客のアプリは共有のDatexカタログ（org 1）と、自組織のパッケージ（例：tob-*）の両方を参照します。release-treeはルートアプリの組織を（applicationDefinitionId → repo → organizationをたどって）自動検出し、両方をインデックス化するため、顧客自身のパッケージも解決できます。これがないと、古いdxsではそれらが黙って消えます。顧客のアプリを検索するには、dxs source repo list --org-name <CODE>を実行します。

• バージョン名（Service Packを含む）。 バージョン名が指定された場合は、ブランチIDに解決してください。デフォルトグループの一覧にはService Packが含まれないため、20260423.145611.SP.20260604.154933のようなversionNameはそこに表示されません。

  • デフォルトリリース：dxs source branch list --repo <id> --default-group --status published -n 0 → versionNameと照合
  • Service Pack：dxs source servicepack list --repo <id>でSPグループを見つけてから、dxs source branch list --repo <id> --group-id <sp_group> --status published -n 0
  • （branch searchで照合されるのはブランチ名であり、versionNameではありません。使用しないでください。）

  これはルートアプリ自身のバージョン名を手動で解決する手順です。依存関係については、dxs ≥ 0.4.24ではrelease-treeがSPへのフォールバックを処理します。詳しくはPhase 1bを参照してください。

ワークフロー

[Phase 1: Enumerate]
dxs source release-tree --from <root_old> --to <root_to>   (--recursive if nested)
  → root + every changed dependency, each resolved to from/to branch IDs
    (cross-org), plus added / removed packages
        |
[Phase 1b: Recover unresolved deps]   summary.resolve_failed must reach 0
Usually empty on dxs >= 0.4.24 (SP groups resolved automatically). If not:
  no repository for uniqueIdentifier -> re-run with --extra-org <orgId>
  still unresolved                   -> manual lookup (see Phase 1b)
  (with --recursive: re-walk each recovered dep — its sub-tree was skipped too)
        |
[Phase 2: Commits per package]
For root + each changed dependency (parallel):
  dxs source compare --from <pkg_old> --to <pkg_new> --exclude-sync
  → committed_branches (id, title, author, date, changes), workitem_ids
        |
[Phase 3: Work Items per commit]
  dxs source workitems --branch <commit_branch_id> --description
        |
[Phase 4: Source Diffs]
For each created/meaningfully-modified/bug-fix config:
  dxs source diff --from <pkg_old> --to <pkg_new> --config <ref_name>
        |
[Phase 5: Write Notes]
Compose two variants per the Output Formats below:
  • Technical — for developers/support
  • Customer — for end users / operations
Deduplicate work items that appear in multiple dependencies. Note added/removed
packages (a newly-included package is a feature; a removed one, a flag).

Phaseの詳細

Phase 1：列挙（release-tree）

dxs source release-tree --from <root_old_branch_id> --to <root_to_branch_id>
# add --recursive only if dependencies have their own changed sub-dependencies;
# a flat aggregator (the common case) is complete in one pass.

この1回の呼び出しで、以前の「メインアプリを比較し、次に各依存関係を再帰的にcompareでたどる」という手順を置き換えられます。次の情報が返されます。

• root — リリース対象のアプリケーション（reference_name、ブランチID）。多くの場合、独自の直接コミットを持たない薄いラッパーです。
• dependencies — 変更された依存関係すべて。それぞれ、すでにrepo_id、from_branch_id、to_branch_id（詳細を調べるのに必要なID）、およびfrom_version／to_versionに解決済みです。組織をまたいで解決されるため、Datexカタログだけでなく、顧客アプリ自身のパッケージ（例：tob-reports）も含まれます。解決できなかった依存関係にはresolve_errorが含まれ、さらに（dxs ≥ 0.4.24では）resolve_failed_sides: ["from"|"to"]も含まれます。どちら側で失敗したかは、このフィールドから読み取ってください。文言であり解析できない; 結合のresolve_error文字列を解析して判断してはいけません。未解決のエントリには、--recursiveでその先をたどれなかった場合、subtree_skipped: trueも含まれます。
• added／removed — リリースに新たに含まれたパッケージ／リリースから削除されたパッケージです。コミット差分を調べる対象ではないため、Phase 5でそのまま記録してください（新たに含まれたパッケージは機能、削除されたパッケージは注意すべき可能性があります）。
• summary — 件数（dependencies_total、resolved_ok、resolve_failed、added_count、removed_count、およびdxs ≥ 0.4.24ではsubtrees_skipped）、さらにmax_depth_reachedとrecursiveが含まれます。--recursiveを指定した場合、max_depth_reachedを--max-depth（デフォルトは10）と比較してください。両者が等しければ、探索が途中で打ち切られた可能性があります。subtrees_skipped > 0はresolve_failed > 0と同じくらい重大です。これは、依存関係をたどれなかったため、変更されたサブツリー全体が列挙されなかったことを示します。

列挙にcompare／deps-diffを使わない理由：解決済みバージョンの差分について、正しい結果が得られるのはdxs ≥ 0.4.9のみです。それより古いビルドでは、変更された依存関係がゼロと報告されます（AppConfigペイロードから削除されたmarketPlaceApplicationVersionIdを比較していたためです）。そのため、実行しても「変更なし」と判断され、依存関係に含まれる80%以上の実質的な変更が見落とされます。release-treeは信頼できる列挙手段であり、詳細を調べるためのブランチIDも返します。

フェーズ 1b：すべての resolve_failed 依存関係を解決する（省略不可）

フェーズ 2 に進む前に、summary.resolve_failed が 0 になっている必要があります。そうでない場合は、残っている失敗をすべて未分析のギャップとして注記に明記してください（このセクションの末尾を参照）。 解決できていない依存関係には少なくとも 1 つのブランチ ID が不足しているため、比較や差分の確認ができません。その依存関係は注記から何も伝えられないまま消えます。これは、このスキルが防ごうとしているまさにその失敗です。0 以外の件数は警告ではなく、進行を妨げる問題として扱ってください。

dxs ≥ 0.4.24 では、このフェーズで対応が不要なことがほとんどです。 summary.resolve_failed と summary.subtrees_skipped を確認し、両方が 0 なら、そのままフェーズ 2 に進んでください。release-tree は Service-Pack で固定された依存関係を自動的に解決します。_published_version_map は、まずリポジトリの Default アプリケーショングループを統合し、そこで見つからないバージョンについては Service Pack グループにフォールバックします（必要なリポジトリでのみ、追加の一覧取得が 1 回行われます）。20260423.145611.SP.20260604.154933 のように .SP. を含む versionName も、通常どおり解決されるようになりました。dxs < 0.4.24 では、参照先が Default グループのみだったため、解決されませんでした。古いビルドを使用している場合は、以下の表を手作業で処理するのではなく、アップグレードしてください（dxs update）。

実際に解決に失敗した場合は、原因に応じて対応します。

シグナル	原因	対応方法
resolve_failed_sides: ["to"]（または ["from"]）	片方のサイドだけが見つかりません。もう一方のブランチ ID は有効です	指定されたサイドだけを復旧してください。すでに取得できている ID は決して破棄しないでください。サイドは ; で連結された resolve_error の説明文を解析するのではなく、このフィールドから読み取ってください。
no repository for uniqueIdentifier …	パッケージの組織がリポジトリのインデックスにありません（repo_id がありません）。release-tree が自動検出するのはルートアプリの組織だけです。	--extra-org <orgId> を指定して再実行してください（繰り返し指定可能で、自動検出された組織に追加されます）。これがインバンドでの修正方法であり、CLI のヘルプにもこの具体的なケースが記載されています。組織 ID がわからない場合に限り、依存関係の reference_name の接頭辞から組織コードを導き出し（tob-reports → TOB）、その組織を dxs source repo list --org-name <CODE> で確認してから、--extra-org を指定して再実行してください。
dxs ≥ 0.4.24 で … not found in published releases	実際に未公開であるか、フォールバックが対象としていないグループタイプです	dxs source servicepack list --repo <repo_id> を実行し、各 SP グループ ID に対して dxs source branch list --repo <repo_id> --group-id <gid> --status published -n 0 を実行します。次に、versionName をエントリの from_version / to_version と照合してください。そこにもない場合、そのバージョンは一度も公開されていません。未分析のギャップとして記録してください。
subtree_skipped: true	--recursive でこのエントリをたどれなかったため、変更されたサブツリー全体が作業リストから抜けています	上記の行に従ってブランチ ID を復旧し、そのエントリを再度たどってください（下記を参照）。summary.subtrees_skipped がこの件数を示します。

復旧したブランチ ID は、release-tree が返した場合とまったく同じようにフェーズ 2 に渡してください。

フェーズ 1 の実行時に --recursive を使用した場合は、復旧した依存関係もそれぞれ再度たどってください。 解決できていない依存関係は次の深さのレベルにキューイングされません。ブランチ ID が不足している項目はすべてスキップされるため、その依存関係自身が持つ変更済みのサブ依存関係も列挙されていません。ブランチ ID を復旧するとパッケージ自体は修正されますが、その下にあるすべての項目は見えないままです。これは同じ種類の見落としが小規模に起きている状態です。

dxs source release-tree --from <recovered_from> --to <recovered_to> --recursive

その出力を作業リストに統合してください。unique_identifier + from_version + to_version（walk が内部で使用するものと同じキー）で重複を除去し、added / removed もフェーズ 5 に引き継いでください。その後、summary.resolve_failed と summary.subtrees_skipped についてフェーズ 1b を再度実行してください。復旧したサブツリーにも、解決できない依存関係が含まれている可能性があります。

どちらの方法を試しても依存関係を解決できない場合は、省略するのではなく、注記にその旨を明記してください（「<package> <from> → <to> を分析できませんでした」）。未分析のパッケージは既知のギャップであり、変更がないことを意味するものではありません。

サービスパックは顧客向けアプリケーションでは一般的です。デフォルトの系列を追跡するのではなく、公開されたリリースを頻繁にホットフィックスするためです。 顧客向けアプリケーションでは、resolve_failed > 0 を想定し、このステップのための予算を確保してください。

フェーズ 2：パッケージごとのコミット

ルートとフェーズ 1 で変更された各依存関係について、コミットを一覧表示します （並列実行 — パッケージごとに処理を展開します）。

dxs source compare --from <pkg_from_branch_id> --to <pkg_to_branch_id> --exclude-sync

branch_comparison から、パッケージごとに次の情報を取得できます。

• committed_branches — マージされた各機能ブランチ：
  • id — コミットのブランチ ID（フェーズ 3 の作業項目に使用します）
  • title — 短いコミット見出し。見出しのみで、リリースノート項目の本文ではありません。本文は作業項目（フェーズ 3）と差分（フェーズ 4）から得られます。
  • author — コミットした人
  • date
  • changes — 設定レベルの変更（reference_name、type、add／update／delete の modification）
• workitem_ids — パッケージの期間全体に関連付けられた DevOps 作業項目。
• releases／release_count — 中間リリース（ヘッダー用）。

--exclude-sync を指定すると、同期のみのコミット（依存関係の更新を取り込むだけのコミット）が除外されます。これらに含まれる実際の作業は、依存関係自体が作業リスト内の独立したパッケージとして扱われるため、そこで把握できます。ルートアプリが小規模な場合、コミット済みブランチが 0 件でも問題ありません。リリース内容が依存関係の更新のみである場合もあります。

コミット済みブランチごとに、commit-release-notes を使用して、利用可能であれば commitReleaseNotes も取得してください。リリース間の source compare と source release-notes では、再構成された committed_branches のノートは省略されます。ブランチの詳細情報／履歴から、返されたコミット ID ごとに補完してください。リリース以外の比較では、API が提供するノートが branch_comparison.commits に保持される場合があります。ノートが見つからない、または null でも問題ありません。また、ノートが入力されていても、API のフォールバック／補完後に単に説明が繰り返されている場合があります。詳細な文章がある場合も、作業項目と差分の分析を続けてください。ノートは補足的な根拠であり、実装の証明ではありません。

フェーズ 3：コミットごとの作業項目

changes 配列が空でないコミット（または範囲が許す場合はすべてのコミット）について、関連付けられた作業項目を取得します。

dxs source workitems --branch <commit_branch_id> --description

作業項目は、リリースノートのビジネス上の背景を把握するうえで最も価値のある入力です。次の情報が含まれます。

• title — 簡潔な機能名（多くの場合、コミットのタイトルより詳しく説明されています）
• type — Development／Bug／Wavelength Component など
• state — Done／Committed など
• assigned_to — 作成者の帰属情報
• description — 要件、再現手順、モックアップ、受け入れ基準の全容

コミットに関連付けられた作業項目がない場合は、「Missing traceability」として明記し、フェーズ 4 の差分を基に、保存済みのコミットノートがあれば補足情報として本文を再構成してください。項目の見出しにはコミット ID と title を使用します。これらを黙って省略してはいけません。

根拠の役割：

• 作業項目（フェーズ 3） — なぜ。ビジネス上の意図、要件、受け入れ基準です。ノートの説明文を作成するための主な入力です。

• 差分（フェーズ 4） — どのように。コードそのものであり、文章と実際にコミットされた内容が一致しない場合の最終的な正解です。

• 保存済みのコミットノート（フェーズ 2） — 利用可能な場合のエンジニアリング上の背景情報です。主張を差分と照合し、追跡可能性の確認も維持してください。タイトルは見出しであり、リリースノートの本文ではありません。

フェーズ 4：ソースの差分

興味深い設定ごとに、フェーズ 1 の所有パッケージの from/to ブランチ ID を使って、統合差分を取得します。

dxs source diff --from <pkg_from_branch_id> --to <pkg_to_branch_id> --config <reference_name>

応答には次の内容が含まれます。

• change_type — created / modified / deleted / unchanged
• content — 設定全体（作成された場合）
• diff — 統合差分（変更された場合）

差分を取得するタイミング：

• 新たに作成された設定は必ず差分を確認します。 content には、新しい要素の全体構造（ハブのタブ、フローのロジック、グリッドの列など）が示されます。これにより、ノートに構造の説明を記載できます。
• 大幅に変更された設定の差分を確認します。 1 つの設定が多くのコミットに登場する場合、累積差分を確認すると、実際に何が変更されたかを最もよく把握できます。
• バグ修正の差分を確認します。 修正は 1、2 行の変更であることがよくあります。差分を確認すれば、その修正が作業項目で報告された問題に対応しているかどうかがわかります。

設定タイプ → 内容を確認する場所：

タイプ	説明する内容
hub	ナビゲーション構造、タブ、アクションバー
flow / footprintFlow	バックエンドのビジネスロジック
frontendFlow	UI の操作とナビゲーション
form / editor	ユーザーインターフェース画面
grid	データ表示、列、フィルター
selector	ドロップダウン／ピッカーの選択肢
datasource	データ取得クエリ
storage	状態管理（多くの場合 MongoDB）

変更タイプ：

• add — 新しい設定であり、新機能の可能性があります。必ず差分を確認してください。
• update — 変更済みです。重要な変更か軽微な変更かは、差分を確認して判断します。
• delete — 削除済みです。破壊的変更の可能性があるため、明記してください。

規模への対応：機能は依存パッケージに存在します（省略不可）

ルートアプリのコミットは、同期コミットにすぎないことが多く、コミットがない場合もあります。「Wave Planning」、「Cart Management」、「Order Import」などの実際の機能は、コンポーネントパッケージ（Waves、Carts、Inventory、FootprintManager など）に存在します。release-tree はフェーズ 1 でそれらをすでに列挙し、解決しています。必要なのは、ルートだけでなく、すべてのパッケージに対してフェーズ 2～4 を実行することです。依存関係の分析を省略すると、実際の変更の 80% 以上を見落とします。

規模に対応するにはサブエージェントを使います。 FootprintManager クラスのリリースには 20～60 個のパッケージと数百のコミットが含まれるため、1 つのコンテキストで扱うには量が多すぎます。並列 Agent（パッケージごと、または約 5 件のコミットごとのバッチ）を起動してフェーズ 2～4 を実行し、ノートを作成するときに調査結果を集約します。この処理を大量かつ決定論的に行う方法（事前に作成した作業リストを使い、低コストモデルでリーフ／リデュース処理を行う方法）については、datex/skills#16 で追跡されている v2 アーキテクチャを参照してください。

フェーズ 5：ノートを作成する

テクニカル版とカスタマー版の両方を作成します。

必須要件（両方の版）

機能とバグ修正の各項目には、必ず次の内容を含めてください。

1. 作業項目へのリンク — 作業項目の内部 ID ではなく、external_id から作成した DevOps へのクリック可能な URL： [#XXXXXX](https://dev.azure.com/DatexCorporation/_workitems/edit/XXXXXX) （_apis/wit/workItems/ API エンドポイントではなく、_workitems/edit/ のブラウザーパス）。作業項目がない場合は「Missing traceability」と記載し、コミット ID を使用します。
2. ビジネスコンテキスト — 作業項目の説明に記載された背景と目的。
3. 作成者の帰属 — 実装者（作業項目またはコミットから特定）。
4. 技術的詳細 — 追加または変更された設定（テクニカル版のみ）。

作業項目へのリンクがないリリースノートは不完全です。追跡可能性がなく、読者が詳細を確認する手段もありません。

重複の排除

同じ作業項目が複数の依存パッケージに現れることがあります（例：Waves と FootprintManager の両方に関連する機能）。最終的なノートを作成する際は、作業項目 ID で重複を排除してください。依存パッケージごとに繰り返すのではなく、機能を 1 回だけ記載し、複数のモジュールにまたがることを明記します。

出力形式

テクニカルリリースノート

# Release Notes — <app>  (<from_version> → <to_version>)

## Summary
- Date range: <from_date> → <to_date>
- Intermediate releases: <count>
- Dependencies updated: <count>

## New Features

### <Feature Title from Work Item>
**Work Item:** [#NNNNNN](…/_workitems/edit/NNNNNN)
**Author:** <Name>

<Description from the work item requirements.>

**Structure / Technical Details:**
- <What was created — new configs, tabs, flows>
- <Key structural notes from the diff>

**New configurations:** <count> configs including <brief list>.

---

## Improvements
<same shape as Features, for enhancements to existing functionality>

---

## Bug Fixes

### <Bug Title from Work Item>
**Work Item:** [#NNNNNN](…/_workitems/edit/NNNNNN)
**Author:** <Name>

**Problem:** <What users experienced — from work item description.>
**Fix:** <What was actually changed — from the source diff.>

---

## Dependencies Updated

| Dependency | From | To | Significant Changes |
|---|---|---|---|
| Waves | <ver> | <ver> | Wave planning feature, N bug fixes |
| …      | …    | …  | …                                 |

顧客向けリリースノート

• 対象読者： エンドユーザー、倉庫管理者、運用スタッフ。
• トーン： 明快でプロフェッショナルな文章。情報を伝え、宣伝文句は使いません。
• 「利用者にとってどのような意味があるか」に重点を置く： 実用面での影響。
• 省略するもの： 設定名、ブランチ ID、内部の技術的詳細。

# What's New — <app>  <from_version> → <to_version>

## New Capabilities

### <Feature Title>
<Two to four sentences in plain language explaining what the user can now do
and why it matters. No config names, no branch IDs.>

---

## Improvements

- <Short sentence per improvement, focused on user-visible impact.>
- <…>

---

## Fixes

- <Short sentence per fix describing the user-visible problem that is no
  longer happening.>
- <…>

顧客向けノートで避けるべきパターン：

• 絵文字の多用（ビジネスソフトウェアではプロフェッショナルさに欠けます）
• 宣伝文句（「お知らせできることをうれしく思います……」など）
• 技術用語（設定名、ブランチ ID、フロー名）
• 曖昧な説明（「さまざまな改善」、「バグ修正」など）

ヒント

1. コードが信頼できる唯一の情報源です。 コミットタイトルや作業項目は手掛かりになりますが、実際の背景はコードにあります。そのため、フェーズ 4 の差分は必須です。
2. すべての機能ブランチに作業項目が必要です。 存在しない場合は「追跡可能性の欠如」としてフラグを立て、取り繕わないでください。
3. 新しい設定の差分を確認して構造を把握します。 ハブのタブ、フローのロジック、グリッドの列は、いずれも add 設定の差分で確認できます。
4. バグ修正の内容は差分に表れます。 複雑そうに聞こえるバグでも、修正は 1 行だけの場合があります。技術的なノートには実際の変更を記載してください。
5. 機能の本体は依存関係にあります。 パッケージのリリースツリーに含まれるすべての項目に対してフェーズ 2～4 を実行すると、内容の 80% が明らかになることもよくあります。特に、独自のアプリにコミットがない、薄い顧客向けラッパーでは重要です。
6. 大規模な分析にはサブエージェントを活用します。 60 個を超えるパッケージを順番に分析すると、時間やコンテキストの制限に達します。並列エージェントを使えば解決できます。
7. 慎重に集約します。 複数の依存関係に登場する作業項目は重複を排除してください。同じ機能が 2 か所で変更されているだけです。

セッション例

# Step 1 (Phase 1): Enumerate the worklist — root + every changed dependency,
# each resolved to from/to branch IDs, cross-org.
dxs source release-tree --from 64920 --to 67162
# root + 19 changed deps (e.g. Waves 64876→67102), 0 resolve_failed, 1 added

# Step 2 (Phase 2): Commits for the Waves dependency
dxs source compare --from 64876 --to 67102 --exclude-sync
# 12 committed_branches with wave planning work

# Step 3 (Phase 3): Why — the work item behind a commit
dxs source workitems --branch 67099 --description
# Work item #180436 — wave creation requirements

# Step 4 (Phase 4): How — the new flow's code
dxs source diff --from 64876 --to 67102 --config create_annotation_task_action

# Bug fix: why then how
dxs source workitems --branch 66852 --description        # Bug #238852
dxs source diff --from 64919 --to 67159 \
  --config outbound_orders_eligible_for_return_grid
# agGrid: null → agGrid: true

よくある間違い

間違い	修正方法
compare／deps-diff で依存関係を列挙する	dxs < 0.4.9 では機能しません（変更数が常に 0 と報告されます）。source release-tree を使用してください
ルートアプリのコミットが少ない、またはないことを理由に「何も変わっていない」と結論づける	薄いラッパーのリリースは、依存関係の更新そのものです。列挙されたすべての依存関係のリリースツリーに対して、フェーズ 2～4 を実行してください
source compare に詳細なコミットノートが含まれると思い込む	実際の出力を確認してください。必要に応じて commit-release-notes から commitReleaseNotes を取得し、欠落しているテキストや要約のみのテキストについては、作業項目や差分で補ってください
顧客向けアプリで Datex-org のパッケージだけを解決する	release-tree は組織をまたいで解決します。顧客自身の *- パッケージも対象です
summary.resolve_failed > 0 のままフェーズ 2 に進む	それらのパッケージはノートから気づかれないまま抜け落ちます。コミットを調べる前に、フェーズ 1b に従ってそれぞれを復旧してください
summary.subtrees_skipped > 0 のままフェーズ 2 に進む	列挙されていないのは単一のエントリではなく、変更されたサブツリー全体です。フェーズ 1b に従って復旧し、再度たどってください
どちらの側で失敗したかを調べるために、; で連結された resolve_error 文字列を解析する	resolve_failed_sides を確認してください（dxs ≥ 0.4.24）。resolve_error は説明文であり、解析できません
Service-Pack で固定された依存関係を手作業で復旧する	dxs ≥ 0.4.24 では release-tree が SP グループを自動的に解決します。復旧表を操作するのではなく、dxs update でアップグレードしてください
no repository for uniqueIdentifier を手動検索だけで対処するケースだと見なす	--extra-org <orgId> を付けて再実行してください（dxs ≥ 0.4.24）。このフラグはまさにこのケースのためのものです
--recursive の実行で、依存関係のブランチ ID を復旧したものの、再度たどらない	解決に失敗した時点で、そのサブツリーの走査はスキップされています。復旧した ID で release-tree --recursive を再実行してください（フェーズ 1b）
コミットタイトルを機能タイトルとして使う	リンク先の作業項目のタイトルを使用してください。コミットタイトルは急いで付けられていることがよくあります
内部 ID や _apis/ URL から DevOps リンクを作成する	external_id と _workitems/edit/ のブラウザーパスを使用してください
同じ機能を複数の依存関係に重複して記載する	まとめる際に作業項目 ID で重複を除去してください
「ノートをすっきりさせるため」に作業項目へのリンクを省略する	リンクは必須です。リンクがないとノートの追跡可能性が失われます
顧客向けノートに設定名やブランチ ID を含める	内部用語を取り除いてください。顧客向けの内容は文章であり、設定情報の寄せ集めではありません
50 件を超える依存関係を順番に分析する	並列のエージェントを使用してください。順番に実行すると、コンテキストや時間の制限に達します