From 4308aa3ceed49004bf35bceaa6ad1cefada82553 Mon Sep 17 00:00:00 2001 From: nfttakerun Date: Sat, 20 Dec 2025 18:05:11 +0900 Subject: [PATCH] feat: Add CI/CD pipeline specification document - Create comprehensive specification for GitHub Actions CI/CD pipeline - Define 4 prioritized user stories (P1: contract auto-test, frontend auto-build, P2: linter, monorepo optimization) - Specify 14 functional requirements (FR-001 to FR-014) - Document 7 success criteria for CI execution - Include edge cases and detailed implementation notes - Cover both contract-ci.yml and frontend-ci.yml workflows - Define trigger settings and cache strategy Relates to #3 --- .specify/memory/cicd-pipeline-spec.md | 164 ++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 .specify/memory/cicd-pipeline-spec.md diff --git a/.specify/memory/cicd-pipeline-spec.md b/.specify/memory/cicd-pipeline-spec.md new file mode 100644 index 0000000..6ad7709 --- /dev/null +++ b/.specify/memory/cicd-pipeline-spec.md @@ -0,0 +1,164 @@ +# 機能仕様書: CI/CDパイプラインの設定 + +**Feature Branch**: `issue-3-cicd-pipeline` +**Created**: 2025-12-20 +**Status**: Draft +**Input**: GitHub issue #3 - CI/CDパイプラインの設定 + +## ユーザーシナリオとテスト *(必須)* + +### ユーザーストーリー1 - コントラクトの自動テスト実行 (優先度: P1) + +開発者がコントラクトのコードを変更してPRを作成すると、自動的にコンパイルとテストが実行され、コードの品質が保証される。 + +**この優先度の理由**: スマートコントラクトのバグは重大な資金損失につながる可能性があるため、最も重要。すべてのコントラクト変更に対してテストを自動実行することで、リグレッションを防ぐ。 + +**独立したテスト**: コントラクトファイルを変更してPRを作成し、GitHub Actionsが自動的にトリガーされ、すべてのSolidityとTypeScriptテストが実行されることを確認できる。 + +**受け入れシナリオ**: + +1. **Given** 開発者がコントラクトコードを変更したとき、**When** PRを作成すると、**Then** GitHub Actionsが自動的にトリガーされコンパイルとテストが実行される +2. **Given** テストが失敗したとき、**When** PR画面を確認すると、**Then** 失敗したテストの詳細が表示され、マージがブロックされる +3. **Given** すべてのテストが成功したとき、**When** PR画面を確認すると、**Then** 緑のチェックマークが表示される + +--- + +### ユーザーストーリー2 - フロントエンドの自動ビルドと型チェック (優先度: P1) + +開発者がフロントエンドのコードを変更してPRを作成すると、自動的に型チェックとビルドが実行され、ビルドエラーや型エラーが早期に検出される。 + +**この優先度の理由**: フロントエンドのビルドエラーは本番環境でのデプロイ失敗につながる。型エラーはランタイムエラーの原因となるため、早期検出が重要。 + +**独立したテスト**: フロントエンドファイルを変更してPRを作成し、GitHub Actionsが自動的にTypeScriptの型チェックとViteビルドを実行することを確認できる。 + +**受け入れシナリオ**: + +1. **Given** 開発者がフロントエンドコードを変更したとき、**When** PRを作成すると、**Then** GitHub Actionsが自動的に型チェックとビルドを実行する +2. **Given** 型エラーまたはビルドエラーがあるとき、**When** PR画面を確認すると、**Then** エラー内容が表示されマージがブロックされる +3. **Given** 型チェックとビルドが成功したとき、**When** PR画面を確認すると、**Then** 緑のチェックマークが表示される + +--- + +### ユーザーストーリー3 - リンターとフォーマッターの自動実行 (優先度: P2) + +開発者がコードを変更してPRを作成すると、自動的にリンターとフォーマッターが実行され、コードスタイルの一貫性が保たれる。 + +**この優先度の理由**: コードの品質と可読性を維持するために重要だが、機能的な不具合には直結しないため、P2とする。 + +**独立したテスト**: コードスタイルに違反するコードを含むPRを作成し、リンターがエラーを検出することを確認できる。 + +**受け入れシナリオ**: + +1. **Given** 開発者がコードを変更したとき、**When** PRを作成すると、**Then** リンター（eslint、solhint）とフォーマッター（prettier）が自動実行される +2. **Given** リンターエラーがあるとき、**When** PR画面を確認すると、**Then** エラー内容が表示される +3. **Given** リンターチェックが成功したとき、**When** PR画面を確認すると、**Then** 緑のチェックマークが表示される + +--- + +### ユーザーストーリー4 - モノレポ全体の効率的なCI実行 (優先度: P2) + +pnpmワークスペースを使用して、変更されたパッケージのみを効率的にテスト・ビルドすることで、CI実行時間を最適化する。 + +**この優先度の理由**: CI時間の最適化は開発者体験の向上につながるが、機能的には必須ではないため、P2とする。 + +**独立したテスト**: 特定のパッケージのみを変更してPRを作成し、そのパッケージのみがテストされることを確認できる。 + +**受け入れシナリオ**: + +1. **Given** コントラクトパッケージのみが変更されたとき、**When** PRを作成すると、**Then** コントラクトのCIワークフローのみが実行される +2. **Given** フロントエンドパッケージのみが変更されたとき、**When** PRを作成すると、**Then** フロントエンドのCIワークフローのみが実行される +3. **Given** 複数のパッケージが変更されたとき、**When** PRを作成すると、**Then** 該当するすべてのCIワークフローが実行される + +--- + +### エッジケース + +- pnpmのキャッシュが破損した場合、CIが失敗するか？ +- node_modulesのインストールに失敗した場合、エラーメッセージは明確か？ +- GitHub Actionsのクォータ制限に達した場合、どのように通知されるか？ +- 並列実行される複数のワークフローがあるとき、依存関係は正しく処理されるか？ +- Hardhatのコンパイルが失敗した場合、エラーログは十分に詳細か？ + +## 要件 *(必須)* + +### 機能要件 + +- **FR-001**: システムは`.github/workflows/contract-ci.yml`を使用してコントラクトのCI/CDパイプラインを実行しなければならない +- **FR-002**: システムは`.github/workflows/frontend-ci.yml`を使用してフロントエンドのCI/CDパイプラインを実行しなければならない +- **FR-003**: コントラクトのCIパイプラインはSolidityのコンパイル（`pnpm run compile`）を実行しなければならない +- **FR-004**: コントラクトのCIパイプラインはすべてのテスト（TypeScriptとSolidityの両方）を実行しなければならない +- **FR-005**: フロントエンドのCIパイプラインはTypeScriptの型チェックを実行しなければならない +- **FR-006**: フロントエンドのCIパイプラインはViteビルドを実行しなければならない +- **FR-007**: すべてのパイプラインはリンター（eslint、solhint）を実行しなければならない +- **FR-008**: すべてのパイプラインはフォーマッター（prettier）のチェックを実行しなければならない +- **FR-009**: PRが作成されたとき、該当するCIパイプラインが自動的にトリガーされなければならない +- **FR-010**: PRがmainブランチにマージされる前に、すべてのCIチェックが成功しなければならない（required status checks） +- **FR-011**: pnpmのバージョンは9.12.0を使用しなければならない +- **FR-012**: Node.jsのバージョンは18.18.0以上を使用しなければならない +- **FR-013**: テストカバレッジレポートをPRコメントとして表示することが望ましい（オプション） +- **FR-014**: CIワークフローはpnpmのキャッシュを活用して実行時間を最適化しなければならない + +### 主要エンティティ + +- **CIワークフロー**: GitHub Actionsで実行される自動化ジョブ。コントラクト用とフロントエンド用の2つのワークフローが存在する。 +- **コントラクトパッケージ**: `packages/contract`配下のSolidityスマートコントラクトとテストコード +- **フロントエンドパッケージ**: `packages/frontend`配下のTypeScript/Reactアプリケーション（想定） +- **pnpmワークスペース**: モノレポ構成を管理し、パッケージ間の依存関係を解決する + +## 成功基準 *(必須)* + +### 測定可能な成果 + +- **SC-001**: PRが作成されてから60秒以内にCIパイプラインがトリガーされる +- **SC-002**: コントラクトのCI実行時間が5分以内に完了する +- **SC-003**: フロントエンドのCI実行時間が5分以内に完了する +- **SC-004**: すべてのテストが成功したPRのみがmainブランチにマージ可能である +- **SC-005**: リンターエラーまたはフォーマッターエラーがあるPRはCIチェックが失敗する +- **SC-006**: コンパイルエラーまたはビルドエラーがあるPRはCIチェックが失敗する +- **SC-007**: 開発者はPR画面でCI失敗の原因を明確に把握できる（エラーログの可視性） + +## 技術スタック + +- **GitHub Actions**: CI/CDプラットフォーム +- **pnpm 9.12.0**: パッケージマネージャー +- **Node.js >=18.18.0**: ランタイム環境 +- **Hardhat v3**: Solidityコンパイルとテスト +- **Vite**: フロントエンドビルドツール +- **TypeScript**: 型チェック +- **eslint/solhint**: リンター +- **prettier**: コードフォーマッター + +## 実装ノート + +### コントラクトCIワークフロー (.github/workflows/contract-ci.yml) + +必要なステップ: +1. Node.js環境のセットアップ +2. pnpmのインストールとキャッシュ設定 +3. 依存関係のインストール (`pnpm install --frozen-lockfile`) +4. Solidityリンターの実行 (`pnpm run lint:sol`) +5. コンパイル (`pnpm run compile`) +6. TypeScriptテストの実行 (`pnpm run test`) +7. Solidityテストの実行 (Foundry使用時) + +### フロントエンドCIワークフロー (.github/workflows/frontend-ci.yml) + +必要なステップ: +1. Node.js環境のセットアップ +2. pnpmのインストールとキャッシュ設定 +3. 依存関係のインストール (`pnpm install --frozen-lockfile`) +4. TypeScriptリンターの実行 (`pnpm run lint`) +5. Prettierチェック (`pnpm run format:check`) +6. 型チェック (`pnpm run type-check`) +7. ビルド (`pnpm run build`) + +### トリガー設定 + +両ワークフローは以下のイベントでトリガー: +- `pull_request` (mainブランチへのPR) +- `push` (mainブランチへのプッシュ) + +### キャッシュ戦略 + +- pnpmのキャッシュを使用して依存関係のインストール時間を短縮 +- Hardhatのコンパイルキャッシュを保存（オプション）