Skip to content

機能仕様書: PRベースの自動マージ機能 #92

New issue
New issue
Open
Open
機能仕様書: PRベースの自動マージ機能#92
Labels
gwt-specGWT spec management
@akiojin

Description

@akiojin
akiojin
opened on Mar 5, 2026

Spec

機能仕様書: PRベースの自動マージ機能

機能ID: SPEC-bf408776
作成日: 2025-10-29
ステータス: 下書き
入力: ユーザー説明: "PRベースの自動マージ機能 - featureブランチの開発完了時に、GitHub Pull Requestを自動作成し、CI/CDチェック成功後に自動的にmainブランチへマージする機能"

ユーザーシナリオ＆テスト (必須)

ユーザーストーリー1 - 自動PR作成 (優先度: P1)

開発者がfeatureブランチでの作業を完了したとき、手動でGitHub PR作成画面を開いてフォームを入力する代わりに、finish-feature.shスクリプトを実行するだけで、SPEC情報を含む適切に構成されたPRが自動的に作成される。

この優先度の理由: PRの作成は開発フローの中核であり、この自動化なしでは後続のRequiredチェックと自動マージが機能しません。最も基本的な価値提供要素です。

独立テスト: finish-feature.shスクリプトを実行し、GitHub上にPRが正しく作成されたことを確認することで完全にテストできます。

受け入れシナリオ:

  1. 前提 開発者がfeature/SPEC-xxxxブランチで作業完了、実行 finish-feature.shを実行、結果 GitHub上にPRが自動作成され、タイトルがspec.mdから取得される
  2. 前提 SPECディレクトリにspec.mdが存在、実行 finish-feature.shを実行、結果 PRボディにSPEC情報（機能ID、説明、変更サマリー）が含まれる
  3. 前提 --draftオプション付きで実行、実行 finish-feature.sh --draftを実行、結果 ドラフトPRとして作成され、自動マージ対象外となる

ユーザーストーリー2 - Requiredチェック監視 (優先度: P2)

PRが作成されたとき、プロジェクトマネージャーはGitHubブランチ保護でRequiredとして指定されたチェック結果だけを根拠に自動マージ可否を判断できる。システムは新たにテストやビルドを実行せず、GitHubが報告するRequiredチェックのステータスを監視し、開発者へ即座にフィードバックを返す。

この優先度の理由: 必須チェックに判断を集約することで、不要なテスト実行を排除しつつ、組織で合意された品質ゲートを確実に守れるため。P1の自動PR作成の後段にある最小限の審査ステップとして不可欠です。

独立テスト: Requiredチェックを意図的に失敗させたPRを作成し、自動マージが保留されることを確認する。Requiredチェックを成功させたPRでは自動マージ準備完了が表示されることを確認する。

受け入れシナリオ:

  1. 前提 Requiredチェックの1つが失敗、実行 PRを作成、結果 GitHubステータスが失敗となり、自動マージは保留され理由がPRに表示される
  2. 前提 Requiredチェックが進行中、実行 PRを作成、結果 GitHubステータスがPendingのままとなり、自動マージもPendingで待機する
  3. 前提 Requiredチェックのみが成功し、任意チェックが失敗、実行 PRを作成、結果 自動マージ準備完了が表示され、任意チェックはブロックしない
  4. 前提 Requiredチェックがすべて成功、実行 PRを作成、結果 自動マージ準備完了が表示される

ユーザーストーリー3 - 自動マージ実行 (優先度: P3)

すべてのRequiredチェックが成功したとき、開発者が手動でマージボタンを押すことなく、システムが自動的にmainブランチへマージし、マージコミット形式で履歴を保持する。

この優先度の理由: 自動マージは最終段階の自動化であり、P1とP2が完成して初めて価値を発揮します。承認待ちやマージ忘れを防ぐ追加の利便性を提供します。

独立テスト: Requiredチェックがすべて成功するPRを作成し、一定時間後にmainブランチに自動的にマージされ、マージコミットが作成されることで検証できます。

受け入れシナリオ:

  1. 前提 PRが作成され、すべてのRequiredチェックが成功、実行 チェック完了後待機、結果 PRが自動的にmainブランチへマージされる
  2. 前提 自動マージ実行時にコンフリクトが発生、実行 マージ試行、結果 マージが中断され、手動解決を促すコメントがPRに追加される
  3. 前提 ドラフトPRが作成されている、実行 Requiredチェックがすべて成功、結果 自動マージはスキップされ、ドラフト解除待ちのステータスが表示される
  4. 前提 自動マージが成功、実行 マージ履歴確認、結果 --no-ffオプションでマージコミットが作成され、履歴が保持されている

ユーザーストーリー4 - リリース自動化 (優先度: P4)

mainブランチへのPRマージが完了したとき、開発者が手動でバージョンアップコマンドを実行したりタグを作成したりすることなく、システムがコミットメッセージを解析して適切なバージョンを自動決定し、npm package、Unity Package、lspバイナリを同一バージョンで自動的にリリースする。

この優先度の理由: リリース自動化は開発フローの最終段階であり、P1〜P3の自動マージ基盤が完成して初めて価値を発揮します。手作業によるバージョン管理の負担とヒューマンエラーを排除します。

独立テスト: Conventional Commitsに従ったコミットでPRをマージし、一定時間後にnpmレジストリに新バージョンが公開され、GitHub Releaseに全アセット（lspバイナリ、manifest.json）が添付されることで検証できます。

受け入れシナリオ:

  1. 前提 feat:コミットを含むPRがmainにマージ、実行 自動リリースフロー実行、結果 minorバージョンアップし（例: 2.16.3→2.17.0）、unity-cli、Unity Package、lspが同一バージョンでリリースされる
  2. 前提 fix:コミットを含むPRがmainにマージ、実行 自動リリースフロー実行、結果 patchバージョンアップし（例: 2.16.3→2.16.4）、全コンポーネントがリリースされる
  3. 前提 BREAKING CHANGE:を含むPRがmainにマージ、実行 自動リリースフロー実行、結果 majorバージョンアップし（例: 2.16.3→3.0.0）、全コンポーネントがリリースされる
  4. 前提 chore:やdocs:のみのPRがmainにマージ、実行 自動リリースフロー実行、結果 バージョンアップせず、リリースもスキップされる
  5. 前提 リリースフロー実行中にlspビルドが失敗、実行 npm publish実行、結果 lsp-manifest.json待機タイムアウトでnpm publishが中断され、開発者に通知される
  6. 前提 リリース完了、実行 CHANGELOG.md確認、結果 前回リリースからの全コミットが自動整形されて記載されている

ユーザーストーリー5 - Worktree境界保護 (優先度: P2.5)

開発者がWorktree内で作業中、誤ってWorktree外へのcd移動、ファイル操作、gitブランチ操作を実行しようとしたとき、システムが自動的にブロックし、適切なエラーメッセージを表示して、Worktree内での作業完結を強制する。

この優先度の理由: Worktree境界保護は、P2（Requiredチェック監視）とP3（自動マージ実行）の間に位置する重要な安全機構です。複数のWorktreeが並行稼働する環境で、誤った操作による他Worktreeへの影響を防ぎ、開発フローの整合性を保証します。

独立テスト: PreToolUse Hooksスクリプト（block-cd-command.sh、block-file-ops.sh、block-git-branch-ops.sh）を通じて、Worktree外への各種操作が適切にブロックされ、Worktree内の操作が許可されることを検証できます。

受け入れシナリオ:

  1. 前提 開発者がWorktree内でcd ..を実行、実行 コマンド送信、結果 Worktree外への移動がブロックされ、エラーメッセージが表示される
  2. 前提 開発者がWorktree内でcd srcを実行、実行 コマンド送信、結果 Worktree内のサブディレクトリへの移動が許可される
  3. 前提 開発者がmkdir /tmp/testを実行、実行 コマンド送信、結果 Worktree外へのディレクトリ作成がブロックされる
  4. 前提 開発者がmkdir test-dirを実行、実行 コマンド送信、結果 Worktree内のディレクトリ作成が許可される
  5. 前提 開発者がgit checkout mainを実行、実行 コマンド送信、結果 ブランチ切り替えがブロックされ、Worktreeフロー遵守を促すメッセージが表示される
  6. 前提 開発者がgit branch --listを実行、実行 コマンド送信、結果 読み取り専用コマンドとして許可される
  7. 前提 開発者がtouch /tmp/test.txtを実行、実行 コマンド送信、結果 Worktree外へのファイル作成がブロックされる
  8. 前提 開発者がrm /tmp/test.txtを実行、実行 コマンド送信、結果 Worktree外へのファイル削除がブロックされる
  9. 前提 開発者がcp test.txt /tmp/を実行、実行 コマンド送信、結果 Worktree外へのファイルコピーがブロックされる

エッジケース

  • GitHub CLIが認証されていない場合、finish-feature.shはエラーメッセージを表示し、gh auth loginを促す
  • SPECディレクトリにspec.mdが存在しない場合、PRタイトルはブランチ名から生成される
  • Requiredチェック実行中にmainブランチが更新された場合、自動マージ前に最新のmainとの同期を試みる
  • 複数のPRが同時に自動マージ待ちの場合、GitHub Actionsのキューで順次処理される
  • ネットワーク障害やGitHub API障害時、自動マージは再試行され、失敗時は開発者に通知される
  • semantic-releaseがConventional Commitsを解析できない場合、リリースはスキップされ、ログに警告が記録される
  • lspビルドが20分以内に完了しない場合、npm publishはタイムアウトし、手動介入が必要になる
  • Unity Packageのバージョン同期スクリプトが失敗した場合、リリースは中断され、開発者に通知される

要件 (必須)

機能要件

  • FR-001: システムは finish-feature.sh 実行時に、自動的にGitHub PRを作成する必要がある
  • FR-002: システムは spec.md から機能タイトルを読み取り、PRタイトルに使用する必要がある
  • FR-003: システムは PRボディに SPEC情報（機能ID、説明、変更サマリー）を含める必要がある
  • FR-004: システムは GitHub API を用いて対象ブランチのRequiredチェックステータスを取得する必要がある
  • FR-005: システムは Requiredチェックが全て success になるまで自動マージを開始してはならない
  • FR-006: システムは Requiredに指定されていないチェック結果を理由に自動マージを停止してはならない
  • FR-007: システムは Requiredチェックが失敗またはタイムアウトした場合、PRに理由をコメントし開発者へ通知する必要がある
  • FR-008: システムは Requiredチェックが全て成功した場合、自動的にmainブランチへマージする必要がある
  • FR-009: システムは マージ時に --no-ff オプションを使用し、マージコミット形式で履歴を保持する必要がある
  • FR-010: システムは ドラフトPRを自動マージ対象外とする必要がある
  • FR-011: システムは マージ失敗時（コンフリクトなど）にPRへコメントを追加し、開発者に通知する必要がある
  • FR-012: ユーザーは --draft オプションでドラフトPRを作成できる必要がある
  • FR-013: システムは main と develop ブランチへのPRに対してのみ自動マージを実行する必要がある
  • FR-014: システムは mainブランチへのマージ完了時に semantic-release を自動実行する必要がある
  • FR-015: システムは Conventional Commits形式のコミットメッセージを解析してバージョンタイプ（major/minor/patch）を決定する必要がある
  • FR-016: システムは unity-cli/package.json のバージョンを更新する必要がある
  • FR-017: システムは Unity Package（UnityCliBridge/Packages/unity-cli-bridge/package.json）のバージョンを unity-cli と同期する必要がある
  • FR-018: システムは 前回リリースからの変更内容を CHANGELOG.md に自動生成する必要がある
  • FR-019: システムは リリースコミットを作成し、バージョンタグ（v*）をpushする必要がある
  • FR-020: システムは タグpush時に lsp のマルチプラットフォームビルドを自動実行する必要がある
  • FR-021: システムは lsp ビルド完了後に GitHub Release を作成し、全アセットを添付する必要がある
  • FR-022: システムは lsp-manifest.json の存在を確認してから npm publish を実行する必要がある
  • FR-023: システムは npm レジストリへの公開前にテストを実行する必要がある
  • FR-024: システムは リリースプロセス中のエラーを検知し、開発者に通知する必要がある
  • FR-025: システムは Worktree外へのcd移動をブロックする必要がある
  • FR-026: システムは Worktree外へのファイル操作（mkdir/rmdir/rm/touch/cp/mv）をブロックする必要がある
  • FR-027: システムは gitブランチ操作（checkout/switch/branch/worktree）をブロックする必要がある
  • FR-028: システムは 読み取り専用コマンド（git status、git branch --list等）を許可する必要がある
  • FR-029: システムは Worktree内のサブディレクトリへのcd移動を許可する必要がある
  • FR-030: システムは Worktree内のファイル操作を許可する必要がある

主要エンティティ

  • SPEC: 機能仕様書。機能ID（SPEC-UUID8桁）、タイトル、説明、タスクリストを含む
  • Pull Request: GitHub上のマージリクエスト。タイトル、ボディ、ステータス（draft/open/merged）、チェック結果を持つ
  • Requiredチェック: GitHubブランチ保護でRequiredに設定されたステータスチェック。成功・失敗・Pendingなどの結果を自動マージ判定に利用
  • マージコミット: 自動マージ時に作成されるGitコミット。--no-ffオプションで履歴を保持
  • Conventional Commit: セマンティックバージョニングに対応したコミットメッセージ形式（feat:, fix:, BREAKING CHANGE: 等）
  • Release: npm package、Unity Package、lspバイナリの公開バージョン。同一バージョン番号で統一管理
  • semantic-release: Conventional Commitsを解析して自動的にバージョニング・リリースノート生成・パッケージ公開を実行するツール
  • CHANGELOG.md: 各バージョンの変更履歴を記録したマークダウンファイル。semantic-releaseが自動生成
  • lsp-manifest.json: lspバイナリのダウンロードURLとSHA256ハッシュを記載したマニフェストファイル。npm publish前に必須
  • PreToolUse Hook: Claude Codeがコマンド実行前に呼び出すスクリプト。Worktree境界を越える操作を検証しブロックする。3つのHooks（block-cd-command.sh、block-file-ops.sh、block-git-branch-ops.sh）で構成

スコープ外 (オプション)

以下の機能は本仕様のスコープ外とし、将来のバージョンで対応予定:

  • コードレビュー承認プロセス（現時点ではRequiredチェックのみで自動マージ）
  • Slack/Teams等への通知連携
  • マージ前の自動コンフリクト解決
  • カスタムチェックルールの動的追加
  • マージ後の自動タグ付け/リリース作成

技術制約 (該当する場合)

  • GitHub CLI（gh）がインストール済みで認証されている必要がある
  • GitHub Actionsの実行権限とシークレット設定が必要
  • Git 2.15以降（worktree機能サポート）が必要
  • Bash 4.0以降（スクリプト実行環境）が必要

前提条件 (該当する場合)

この機能は以下を前提とします:

  • プロジェクトがGitHubでホストされている
  • 既存のfinish-feature.shスクリプトが存在する
  • SPEC駆動開発フロー（spec.md, tasks.md）が採用されている
  • GitHubブランチ保護でRequiredチェックが設定されている

依存関係 (該当する場合)

この機能は以下に依存します:

  • GitHub CLI（gh）: PR作成・管理に使用
  • GitHub Actions / Required Status Checks: ブランチ保護で定義されたRequiredチェック結果を提供
  • GitHubブランチ保護設定: Requiredチェックと自動マージに必要なルールを定義
  • @akiojin/claude-worktree（developブランチ）: 設計思想とワークフロー参考元、PreToolUse Hooks実装の参考元

成功基準 (必須)

以下の成功基準を満たす必要があります:

自動マージ関連

  1. 開発者がPR作成にかける時間が平均5分から30秒以内に短縮される
  2. Requiredチェックが未完了のまま自動マージされるケースがゼロになる
  3. チェック成功後、5分以内に自動マージが完了する
  4. マージ失敗時、10分以内に開発者へフィードバックが提供される
  5. ドラフトPRが誤って自動マージされるケースがゼロになる
  6. 自動マージされたコミットの100%がマージコミット形式（--no-ff）で履歴が保持される
  7. コンフリクト発生時、100%のケースで適切なエラーメッセージがPRに表示される

リリース自動化関連

  1. mainマージ後、手作業なしで5分以内に完全なリリースが完了する
  2. unity-cli、Unity Package、lspが100%同一バージョン番号でリリースされる
  3. Conventional Commitsに基づくバージョン決定の正確性が100%（feat→minor、fix→patch、BREAKING CHANGE→major）
  4. リリース関連のテストカバレッジが80%以上
  5. CHANGELOG.mdが前回リリースからの全コミットを含み、自動生成される
  6. lspビルド失敗時、npm publishが100%中断される（不完全リリース防止）
  7. リリースエラー発生時、10分以内に開発者へ通知される

Worktree境界保護関連

  1. Worktree外への誤操作（cd、ファイル操作、gitブランチ操作）が100%ブロックされる
  2. Worktree内の正当な操作が100%許可される
  3. PreToolUse Hooksのテストカバレッジが100%（15/15テストケース合格）
  4. ブロック時のエラーメッセージが100%適切で、代替手段が提示される

⚡ クイックガイドライン

  • ✅ ユーザーが「何を」必要とし「なぜ」必要なのかに焦点を当てる
  • ❌ 「どのように」実装するかを避ける (技術スタック、API、コード構造なし)
  • 👥 ビジネス関係者向けに記述 (開発者向けではない)

Plan

実装計画: PRベースの自動マージ & リリース自動化

SPEC-ID: SPEC-bf408776
作成日: 2025-10-31
ステータス: Phase 2 (実装計画)

Phase 0: 技術リサーチ

semantic-release調査結果

  • 参考実装: @akiojin/claude-worktree
  • コア機能: Conventional Commits解析、自動バージョニング、CHANGELOG生成、タグ作成、npm publish
  • プラグインシステム: モジュール化された処理（commit-analyzer, release-notes-generator, changelog, npm, git, github）

プロジェクト固有の要件

本プロジェクトは3つのリリース対象を持つ：

  1. unity-cli (Node.js package) → npm registry
  2. Unity Package (UPM package) → バージョン同期のみ（npm非公開）
  3. lsp (C# CLI) → マルチプラットフォームバイナリ（GitHub Release）

技術的課題

  1. Unity Packageのバージョンをunity-cliと同期する仕組み
  2. lspビルドが完了してからnpm publishする順序制御
  3. GitHub Releaseの作成をsemantic-releaseではなくlspワークフローに委譲

Phase 1: 設計とコントラクト

アーキテクチャ概要

┌────────────────────────────────────────────────────────────────┐
│                     Developer Workflow                          │
└────────────────────────────────────────────────────────────────┘
                              │
                              ↓
                    [ finish-feature.sh ]
                              │
                              ↓
┌────────────────────────────────────────────────────────────────┐
│                   Auto-Merge Workflow                           │
│  (既存: .github/workflows/auto-merge.yml)                       │
│   - Required Checks監視                                         │
│   - 自動マージ実行                                               │
└────────────────────────────────────────────────────────────────┘
                              │
                              ↓ main branch
┌────────────────────────────────────────────────────────────────┐
│              Release Workflow (新規)                            │
│  (.github/workflows/release.yml)                                │
│                                                                  │
│  1. Conventional Commits解析 (semantic-release)                 │
│  2. バージョン決定 (major/minor/patch)                          │
│  3. package.json更新                                             │
│     - unity-cli/package.json                                   │
│     - Unity Package package.json (sync script)                  │
│  4. CHANGELOG.md生成                                             │
│  5. リリースコミット作成                                         │
│  6. タグpush (v*)                                                │
└────────────────────────────────────────────────────────────────┘
                              │
                              ↓ tag push
                 ┌────────────┴────────────┐
                 │                          │
                 ↓                          ↓
┌──────────────────────────────┐   ┌────────────────────────────┐
│  lsp Build Workflow   │   │   (GitHub Release作成待機)  │
│  (既存: release-lsp   │   │                             │
│           .yml)               │   └────────────────────────────┘
│                               │
│  1. 6プラットフォームビルド  │
│  2. lsp-manifest.json │
│     生成                      │
│  3. GitHub Release作成        │
│  4. 全アセット添付            │
└──────────────────────────────┘
                 │
                 ↓ release.published
┌──────────────────────────────────────────────────────────────┐
│          npm Publish Workflow (既存: unity-cli-publish.yml) │
│                                                               │
│  1. lsp-manifest.json存在確認                         │
│  2. テスト実行                                                │
│  3. npm publish                                               │
└──────────────────────────────────────────────────────────────┘

データモデル

Conventional Commit 形式

<type>([scope]): <subject>

[body]

[footer]

type決定ルール:

  • feat: → minor version up (例: 2.16.3 → 2.17.0)
  • fix: → patch version up (例: 2.16.3 → 2.16.4)
  • BREAKING CHANGE: → major version up (例: 2.16.3 → 3.0.0)
  • chore:, docs:, test: → version up なし

バージョン同期

unity-cli/package.json
  ↓ semantic-release
  version: "2.17.0"
  ↓ sync script (prepareCmd)
UnityCliBridge/Packages/unity-cli-bridge/package.json
  version: "2.17.0"

リリース依存関係

semantic-release
  ↓
  tag push (v2.17.0)
  ↓
  ├─→ lsp build (parallel, ~5分)
  │    ↓
  │    GitHub Release作成
  │
  └─→ npm publish workflow待機
       ↓
       manifest確認 (最大20分)
       ↓
       npm publish実行

コントラクト定義

1. semantic-release設定 (.releaserc.json)

{
  "branches": ["main"],
  "tagFormat": "v${version}",
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "@semantic-release/changelog",
      {
        "changelogFile": "CHANGELOG.md"
      }
    ],
    [
      "@semantic-release/exec",
      {
        "prepareCmd": "node scripts/sync-unity-package-version.js ${nextRelease.version}"
      }
    ],
    [
      "@semantic-release/npm",
      {
        "npmPublish": false,
        "pkgRoot": "unity-cli"
      }
    ],
    [
      "@semantic-release/git",
      {
        "assets": [
          "unity-cli/package.json",
          "UnityCliBridge/Packages/unity-cli-bridge/package.json",
          "CHANGELOG.md"
        ],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

重要: @semantic-release/githubプラグインは使用しない（lspワークフローがRelease作成）

2. Unity Packageバージョン同期スクリプト

ファイル: scripts/sync-unity-package-version.js

/**
 * Sync Unity Package version with unity-cli version
 * Called by semantic-release prepareCmd
 */
const fs = require('fs');
const path = require('path');

const version = process.argv[2];
if (!version) {
  console.error('Version argument is required');
  process.exit(1);
}

const unityPackageJsonPath = path.join(
  __dirname,
  '../UnityCliBridge/Packages/unity-cli-bridge/package.json'
);

const packageJson = JSON.parse(fs.readFileSync(unityPackageJsonPath, 'utf8'));
packageJson.version = version;
fs.writeFileSync(unityPackageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');

console.log(`Unity Package version synced to ${version}`);

3. Release Workflow

ファイル: .github/workflows/release.yml

name: Release

on:
  push:
    branches:
      - main

permissions:
  contents: write
  issues: write
  pull-requests: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'

      - name: Install dependencies
        working-directory: unity-cli
        run: npm ci

      - name: Run tests
        working-directory: unity-cli
        run: npm run test:ci

      - name: Semantic Release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: npx semantic-release

4. lsp Workflow更新

ファイル: .github/workflows/release-lsp.yml

変更点:

  • GitHub Release作成ステップを追加
  • softprops/action-gh-release@v2でリリース作成
  • CHANGELOG.mdから該当バージョンのノートを抽出

5. npm Publish Workflow更新

ファイル: .github/workflows/unity-cli-publish.yml

変更点:

  • トリガーを release.publishedに変更
  • 既存のmanifest待機ロジックは維持

憲章チェック

✅ TDD遵守

  • テストファイルを先に作成（RED）
  • 実装後にテスト合格（GREEN）
  • リファクタリング（REFACTOR）

✅ ハンドラーアーキテクチャ

semantic-releaseはプラグインベースで拡張性があり、既存のハンドラーアーキテクチャと整合

✅ LLM最適化

  • CHANGELOG.mdで変更履歴を自動文書化
  • Conventional Commitsで意図が明確
  • コミットメッセージがそのままリリースノートに

✅ シンプルさの原則

  • 既存ツール（semantic-release）を活用
  • 最小限のカスタムスクリプト（sync-unity-package-version.js）
  • 既存ワークフロー（auto-merge, lsp, npm-publish）を最大限再利用

Phase 2: タスク計画

Setup Tasks

  • SPEC-bf408776のspec.md更新完了
  • plan.md作成完了
  • tasks.md作成

Test Phase (RED)

  • tests/unit/scripts/sync-unity-version.test.js 作成
    • Unity Package version syncのロジックテスト
    • ファイル読み書きのモックテスト
  • tests/integration/semantic-release.test.js 作成
    • semantic-release設定の妥当性テスト
    • Conventional Commits解析テスト
  • tests/e2e/release-flow.test.js 作成
    • featureブランチでのドライラン
    • バージョンアップフロー E2E テスト

Implementation Phase (GREEN)

  • .releaserc.json 作成
  • scripts/sync-unity-package-version.js 実装
  • .github/workflows/release.yml 作成
  • .github/workflows/release-lsp.yml 更新（Release作成追加）
  • .github/workflows/unity-cli-publish.yml 更新（トリガー変更）
  • unity-cli/package.json に semantic-release 依存追加

Documentation Phase

  • README.md 更新（リリースプロセスセクション追加）
  • CLAUDE.md 更新（バージョン管理セクション更新）
  • SPEC完了確認

Integration Phase

  • featureブランチでドライラン
  • mainマージ＆本番リリース検証
  • finish-feature.sh実行（PR作成）

Quickstart

開発者向けリリースフロー

  1. 通常の開発: featureブランチでConventional Commitsを使用

    git commit -m "feat: Add new screenshot mode"
git commit -m "fix: Resolve path resolution issue"

  2. PR作成: finish-feature.sh実行

    .specify/scripts/bash/finish-feature.sh

  3. 自動マージ: Required Checks成功後、自動的にmainへマージ

  4. 自動リリース: mainマージ後、以下が自動実行

    • semantic-releaseがコミット解析
    • バージョン決定（feat→minor、fix→patch）
    • package.json更新（unity-cli + Unity Package）
    • CHANGELOG.md生成
    • タグpush (v2.17.0)
    • lspビルド開始
    • GitHub Release作成
    • npm publish実行

  5. 完了確認: npmレジストリとGitHub Releaseを確認

注意事項

  • [skip ci]付きコミット: リリースコミット自体は[skip ci]でCIスキップ
  • ブランチ保護: semantic-releaseボットによるchore(release)コミットを許可
  • シークレット: NPM_TOKEN必須、GITHUB_TOKENは自動提供

リスク＆軽減策

リスク1: lspビルド失敗でnpm publishが中断

軽減策:

  • unity-cli-publish.ymlでmanifest待機（最大20分）
  • タイムアウト時はエラー通知
  • 手動再実行可能（workflow_dispatch）

リスク2: Unity Packageバージョン同期失敗

軽減策:

  • sync-unity-package-version.jsでエラーハンドリング
  • 失敗時はsemantic-releaseプロセス全体が中断
  • ユニットテストで検証

リスク3: Conventional Commits規約違反

軽減策:

  • commitlint導入（PRチェック）
  • ドキュメント整備（README.md）
  • 違反時は自動リリーススキップ（警告ログ）

参考資料

Tasks

タスクリスト: PRベースの自動マージ & リリース自動化

SPEC-ID: SPEC-bf408776
作成日: 2025-10-31

Setup Tasks

  • S001: SPEC-bf408776のspec.md更新（リリース自動化要件追加）
  • S002: plan.md作成（semantic-release技術設計）
  • S003: tasks.md作成（このファイル）

Test Tasks（RED Phase）

Unit Tests

  • T001 [P]: Unity Packageバージョン同期スクリプトのテスト作成

    • ファイル: tests/unit/scripts/sync-unity-version.test.js

    • 目的: sync-unity-package-version.jsの動作検証

    • 検証内容:

      • 正常系: バージョン引数を受け取りUnity package.jsonを更新
      • 異常系: バージョン引数なしでエラー終了
      • 異常系: Unity package.json読み込み失敗

    • 期待結果: テスト失敗（RED）

  • T002 [P]: CHANGELOG生成テスト作成

    • ファイル: tests/unit/changelog.test.js

    • 目的: semantic-releaseのCHANGELOG生成が正しく動作するか

    • 検証内容:

      • feat/fix/BREAKING CHANGEコミットが正しく分類される
      • マークダウン形式が正しい

    • 期待結果: テスト失敗（RED）

Integration Tests

  • T003: semantic-release設定の統合テスト作成

    • ファイル: tests/integration/semantic-release.test.js
    • 目的: .releaserc.json設定の妥当性検証
    • 検証内容:
      • Conventional Commits解析が正しく動作
      • バージョン決定ロジック（feat→minor、fix→patch）
      • Unity Packageバージョン同期が実行される
      • CHANGELOG.mdが生成される
    • 期待結果: テスト失敗（RED）

  • T004: リリースワークフロー統合テスト作成

    • ファイル: tests/integration/release-workflow.test.js
    • 目的: GitHub Actionsワークフロー連携の検証
    • 検証内容:
      • mainマージ → semantic-release実行
      • タグpush → lspビルド起動
      • GitHub Release作成 → npm publish起動
    • 期待結果: テスト失敗（RED）

E2E Tests

  • T005: リリースフローE2Eテスト作成
    • ファイル: tests/e2e/release-flow.test.js
    • 目的: エンドツーエンドリリースフローの検証
    • 検証内容:
      • featureブランチでConventional Commitsを作成
      • PRマージ後にバージョンアップ
      • npm, Unity Package, lspが同一バージョン
      • CHANGELOG.mdに変更内容が記載
    • 期待結果: テスト失敗（RED）

Core Tasks（GREEN Phase）

Configuration Files

  • C001 [P]: .releaserc.json作成

    • ファイル: .releaserc.json
    • 内容:
      • branches: ["main"]
      • tagFormat: "v${version}"
      • plugins:
        • @semantic-release/commit-analyzer
        • @semantic-release/release-notes-generator
        • @semantic-release/changelog
        • @semantic-release/exec (Unity sync)
        • @semantic-release/npm (npmPublish: false)
        • @semantic-release/git
    • 検証: T003統合テストが合格（GREEN）

  • C002 [P]: package.jsonにsemantic-release依存追加

    • ファイル: unity-cli/package.json
    • 追加内容: 
      "devDependencies": {
  "@semantic-release/changelog": "^6.0.3",
  "@semantic-release/commit-analyzer": "^11.1.0",
  "@semantic-release/exec": "^6.0.3",
  "@semantic-release/git": "^10.0.1",
  "@semantic-release/release-notes-generator": "^12.1.0",
  "semantic-release": "^22.0.12"
}
    • 検証: npm ciが成功

Scripts

  • C003: Unity Packageバージョン同期スクリプト実装
    • ファイル: scripts/sync-unity-package-version.js
    • 実装内容:
      • コマンドライン引数からバージョン取得
      • Unity package.json読み込み
      • versionフィールド更新
      • ファイル書き込み（フォーマット維持）
      • エラーハンドリング
    • 検証: T001ユニットテストが合格（GREEN）

GitHub Actions Workflows

  • C004: Release Workflow作成

    • ファイル: .github/workflows/release.yml
    • 実装内容:
      • トリガー: push to main
      • ステップ:
        1. Checkout (fetch-depth: 0)
        2. Setup Node.js 18
        3. npm ci
        4. npm run test:ci
        5. npx semantic-release
      • 権限: contents: write
    • 検証: T004統合テストが合格

  • C005: lsp Workflow更新（GitHub Release作成追加）

    • ファイル: .github/workflows/release-lsp.yml
    • 変更内容:
      • releaseジョブにbody_path追加
      • CHANGELOG.mdから該当バージョンのノート抽出
      • softprops/action-gh-release@v2でRelease作成
    • 検証: タグpush時にGitHub Releaseが作成される

  • C006: npm Publish Workflow更新（トリガー調整）

    • ファイル: .github/workflows/unity-cli-publish.yml
    • 変更内容:
      • トリガーをrelease.publishedに変更
      • 既存のmanifest待機ロジックは維持
    • 検証: GitHub Release作成後にnpm publishが実行される

Integration Tasks

Documentation

  • I001: README.md更新（リリースプロセスセクション追加）

    • ファイル: README.md
    • 追加セクション:

      • リリースプロセス

        • 自動リリースフローの説明
        • Conventional Commits規約
        • バージョニングルール
        • トラブルシューティング
    • 検証: markdownlintエラーなし

  • I002: CLAUDE.md更新（バージョン管理セクション）

    • ファイル: CLAUDE.md
    • 変更内容:
      • npm versionコマンド → semantic-releaseに更新
      • Conventional Commits規約を追記
      • リリースフロー図を追加
    • 検証: markdownlintエラーなし

Testing & Validation

  • I003: 全テスト実行＆検証

    • コマンド: npm run test:ci
    • 検証内容:
      • すべてのユニットテストが合格
      • すべての統合テストが合格
      • テストカバレッジ80%以上
    • 期待結果: すべてGREEN

  • I004: featureブランチでドライラン

    • 手順:
      1. テストコミット作成（feat: Test release automation）
      2. ローカルでsemantic-release実行（--dry-run）
      3. バージョン決定とCHANGELOG生成を確認
    • 検証: エラーなくドライラン完了

  • I005: finish-feature.sh実行してPR作成

    • 実施内容:
      • finish-feature.shのブランチ名検証を修正（feature/* 全般対応）
      • PR #17を作成
      • GitHub Actions自動マージワークフロー起動
    • 検証: PR正常作成、自動マージ待機中

Polish Tasks

CI/CD Integration

  • P001: commitlint導入（Conventional Commits強制）

    • ファイル: .commitlintrc.json
    • 内容: 
      {
  "extends": ["@commitlint/config-conventional"]
}
    • GitHub Actions: PRチェックに追加
    • 検証: 不正なコミットメッセージでPR失敗

  • P002: リリースノート品質向上

    • カスタムリリースノートテンプレート: 検討
    • セクション分類: Features, Bug Fixes, BREAKING CHANGES
    • 検証: 生成されるCHANGELOG.mdの可読性

Monitoring & Alerts

  • P003: リリース失敗時の通知設定
    • Slack/Discord Webhook: 検討
    • GitHub Issues自動作成: semantic-release失敗時
    • 検証: リリース失敗を意図的に発生させて通知確認

Completion Checklist

  • すべてのSetup Tasksが完了
  • すべてのTest Tasks（RED）が完了
  • すべてのCore Tasks（GREEN）が完了し、テストが合格
  • すべてのIntegration Tasksが完了
  • すべてのPolish Tasksが完了（Optional: commitlint、カオステストなど）
  • SPEC-bf408776の成功基準をすべて満たす
  • ドキュメント（README.md, CLAUDE.md）が最新
  • mainマージ後のリリースが正常に完了（PR作成後に確認）

タスク実行ログ

2025-10-31

  • S001: spec.md更新完了
  • S002: plan.md作成完了
  • S003: tasks.md作成完了
  • T001: Unity同期スクリプトテスト作成完了（RED）
  • C003: Unity同期スクリプト実装完了（GREEN、全テスト合格）
  • C001: .releaserc.json作成完了
  • C002: package.json依存追加完了
  • C004: release.ymlワークフロー作成完了
  • C005: release-lsp.yml更新完了
  • C006: unity-cli-publish.yml更新完了
  • I001: README.md更新完了
  • I002: CLAUDE.md更新完了
  • I003: 全テスト実行＆検証完了（63/63 pass）
  • ワークスペースpackage.json作成＆semantic-releaseドライラン成功
  • I004: semantic-releaseドライラン完了（バージョン決定とCHANGELOG生成確認）
  • I005: finish-feature.shのブランチ名検証修正完了（feature/* 全般対応）
  • PR #17作成完了（https://github.com/akiojin/unity-cli/pull/17）
  • GitHub Actions自動マージワークフロー起動中

注記

  • [P]: 並列実行可能なタスク
  • 依存関係: Test Tasks → Core Tasks → Integration Tasks → Polish Tasks
  • TDDサイクル: 必ずテスト作成（RED）→ 実装（GREEN）→ リファクタリング の順序を守る

TDD

TODO

Research

TODO

Data Model

TODO

Quickstart

TODO

Contracts

Artifact files under contracts/ are managed in issue comments with contract:<name> entries.

Checklists

Artifact files under checklists/ are managed in issue comments with checklist:<name> entries.

Acceptance Checklist

  • Add acceptance checklist

Metadata

Metadata

Assignees

No one assigned

    Labels

    gwt-specGWT spec management

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions