# バッチ設計書 50-vmr-sync.sh

## 概要

本ドキュメントは、VMR同期スクリプト（vmr-sync.sh）の設計仕様を記載したものです。このスクリプトは、現在のリポジトリのコードをVirtual Monolithic Repository（VMR）であるdotnet/dotnetリポジトリに同期します。

### 本バッチの処理概要

このバッチは、DARC（Dependency Auto Update Repository Client）ツールを使用して、個別リポジトリのコードをVMR（dotnet/dotnet）にフォワード同期します。これにより、ソースビルドの検証やVMR統合テストをローカルで実行できます。

**業務上の目的・背景**：.NETは多数の独立したリポジトリ（runtime、aspnetcore、sdk、fsharp等）で開発されていますが、ソースビルド（外部依存なしでのビルド）を実現するために、これらを単一のVMR（Virtual Monolithic Repository）に統合する必要があります。このスクリプトにより、開発者は自分の変更がVMRに統合された際の動作を事前に検証できます。

**バッチの実行タイミング**：ソースビルドの検証が必要な場合、または変更をVMRにテスト統合する際に手動で実行されます。CI/CDパイプラインでも使用される場合があります。

**主要な処理内容**：
1. コマンドライン引数の解析（一時ディレクトリ、VMRパス、ブランチ等）
2. VMRリポジトリの準備（クローンまたは既存リポジトリの確認）
3. .NET SDKとDARCツールのインストール
4. DARC vmr forwardflowコマンドの実行
5. 同期結果の報告

**前後の処理との関連**：tools.shに依存し、InitializeDotNetCliとGetDarc関数を使用します。同期されたVMRは、後続のソースビルドテストで使用されます。

**影響範囲**：指定されたVMRディレクトリ（または一時ディレクトリ下のdotnetディレクトリ）にリポジトリがクローン/更新されます。

## バッチ種別

リポジトリ同期 / VMR統合 / ソースビルド準備

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（VMR統合検証時） |
| 実行時刻 | 手動実行またはCI/CDパイプライン |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行 / CI/CDパイプライン |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| gitコマンド | VMRのクローンと操作用 |
| tools.shの存在 | eng/common/tools.shが存在 |
| ネットワーク接続 | GitHubへのアクセス |
| 一時ディレクトリ | --tmp-dirで指定された書き込み可能なディレクトリ |

### 実行可否判定

- --tmp-dirが指定されていない場合はエラー終了
- VMRに未コミットの変更がある場合はエラー終了

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| -t, --tmp, --tmp-dir | string | Yes | なし | 一時ディレクトリパス |
| -v, --vmr, --vmr-dir | string | No | $tmp_dir/dotnet | VMRディレクトリパス |
| -b, --branch, --vmr-branch | string | No | なし | VMRのブランチ名 |
| --remote | string | No | なし | 追加リモート（name:URI形式） |
| --azdev-pat | string | No | なし | Azure DevOps PAT（プライベートリポジトリ用） |
| --ci | flag | No | false | CI環境モード |
| -d, --debug | flag | No | false | デバッグモード |
| -h, --help | flag | No | false | ヘルプ表示 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| dotnet/dotnetリポジトリ | Git | https://github.com/dotnet/dotnet |
| 現在のリポジトリ | Git | 同期元のソースコード |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| $vmr_dir | Gitリポジトリ | 同期されたVMR |
| 標準出力 | テキスト | 進捗メッセージ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | VMRリポジトリ全体 |
| 出力先 | --vmr-dirで指定、またはデフォルト |
| 文字コード | 該当なし（Gitリポジトリ） |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数の解析
   └─ tmp_dir、vmr_dir、vmr_branch、additional_remotes等
2. 入力検証
   └─ tmp_dirが指定されているか確認
3. 一時ディレクトリの作成
   └─ 存在しない場合は作成
4. VMRリポジトリの準備
   4a. VMRが存在しない場合:
       └─ git clone https://github.com/dotnet/dotnet
       └─ vmr_branch指定時はブランチ作成
   4b. VMRが存在する場合:
       └─ 未コミット変更の確認（あればエラー）
       └─ vmr_branch指定時はチェックアウト＆プル
5. ツールの準備
   └─ tools.shの読み込み
   └─ InitializeDotNetCli実行
   └─ GetDarc実行
6. DARC vmr forwardflow実行
   └─ 追加リモート、Azure DevOps PAT等を指定
7. 結果の報告
   └─ 成功/失敗メッセージの出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{--tmp-dir指定?}
    B -->|なし| C[エラー終了]
    B -->|あり| D[一時ディレクトリ準備]
    D --> E{VMR存在?}
    E -->|なし| F[git clone dotnet/dotnet]
    E -->|あり| G{未コミット変更?}
    G -->|あり| H[エラー終了]
    G -->|なし| I[チェックアウト/プル]
    F --> J[.NET SDK初期化]
    I --> J
    J --> K[DARC取得]
    K --> L[darc vmr forwardflow実行]
    L --> M{成功?}
    M -->|Yes| N[成功メッセージ]
    M -->|No| O[失敗メッセージ]
    N --> P[正常終了]
    O --> Q[終了コード1]
```

## データベース操作仕様

### 操作別データベース影響一覧

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | - | - | このバッチはデータベース操作を行いません |

### テーブル別操作詳細

このバッチはデータベース操作を行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | Missing --tmp-dir | 一時ディレクトリ未指定 | --tmp-dirパラメータを指定 |
| 1 | Working tree changes | VMRに未コミット変更あり | 変更をコミットまたはスタッシュ |
| 1 | Synchronization failed | DARC同期失敗 | ログを確認してパッチファイルを修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

1. エラーメッセージを確認
2. --debugオプションで詳細ログを取得
3. パッチファイルのコンフリクトがある場合は手動で解決
4. VMRディレクトリを削除して再実行（クリーン状態から）

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 同期失敗時、VMRは最後の状態のまま（再実行でリセット可能） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1リポジトリ分の同期 |
| 目標処理時間 | 数分〜数十分（変更量とネットワーク依存） |
| メモリ使用量上限 | DARC/Git依存 |

## 排他制御

同一のVMRディレクトリに対して同時実行しないでください。Gitの競合が発生します。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | クローン時 | "Cloning 'dotnet/dotnet' into..." |
| 情報ログ | 準備時 | "Preparing $vmr_dir" |
| 情報ログ | SDK初期化時 | "Installing .NET, preparing the tooling.." |
| 情報ログ | 同期開始時 | "Starting the synchronization of VMR.." |
| 成功ログ | 同期成功時 | "Synchronization succeeded" |
| エラーログ | 失敗時 | "Synchronization of repo to VMR failed!" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | CI/CDパイプラインの失敗通知 |

## 備考

- VMR（Virtual Monolithic Repository）は、.NETの全コンポーネントを単一リポジトリに統合したものです
  - リポジトリ: https://github.com/dotnet/dotnet
- DARC（Dependency Auto Update Repository Client）は、.NETの依存関係管理ツールです
  - vmr forwardflowコマンドで個別リポジトリからVMRへの同期を行います
- --remoteオプションでフォークからの同期も可能（例: `--remote runtime:https://github.com/yourfork/runtime`）
- --azdev-patオプションはプライベートリポジトリへのアクセスに必要
- 同期失敗時、VMRパッチファイルのコンフリクトが原因の場合が多いです
  - ログに表示されるパッチファイルを確認・修正して再実行してください
- --debugオプションで詳細なログが出力されます（set -x有効化）
