From 1b5f45d339f3732b64fbb27e0a2ebe23b0f2d0ac Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Sun, 23 Aug 2026 01:35:54 +0900 Subject: [PATCH 1/9] =?UTF-8?q?docs:=20project.yml=20=E6=96=B9=E5=BC=8F?= =?UTF-8?q?=E3=81=AE=E3=83=89=E3=82=AD=E3=83=A5=E3=83=A1=E3=83=B3=E3=83=88?= =?UTF-8?q?=E3=82=92=E6=95=B4=E5=82=99=E3=81=99=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PLAN32 Task 5。複数リポジトリ構成と project.yml への移行に合わせて利用者向け ドキュメントを更新した。 - docs/user/project-yml.md を新設: スキーマ、複数リポジトリの例、検証される 内容、env との使い分け、旧 env からの移行表、コンテナへの渡り方 - 環境変数ガイド / コンテナ操作ガイド / CLI リファレンス / プラグイン開発の 各所から旧キー (GIT_USER / GIT_REPO / WORK_DIR / CONTAINER_SCALE) の説明を 外し、project.yml とその参照へ置き換え - CLI リファレンスに devbase project migrate-config を追記 - アーキテクチャ解説に project/ モジュールの節を追加 - CHANGELOG に破壊的変更と再ビルドの注意を追記 過去リリース分の CHANGELOG 記述は履歴なので書き換えていない。 Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 25 ++++ README.md | 1 + docs/README.md | 3 + docs/developer/architecture.md | 20 ++++ docs/plugin-dev/compose-yml-guidelines.md | 28 +++-- docs/plugin-dev/quickstart.md | 66 ++++++++--- docs/plugin-dev/repo-backed-projects.md | 36 +++--- docs/user/cli-reference/02-project.md | 34 +++++- docs/user/container-operations.md | 15 ++- docs/user/environment-variables.md | 24 ++-- docs/user/project-yml.md | 138 ++++++++++++++++++++++ 11 files changed, 326 insertions(+), 64 deletions(-) create mode 100644 docs/user/project-yml.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d401fd..c8080fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,32 @@ ## [Unreleased] +### Changed +- **1 プロジェクト = 1 コンテナ = 複数リポジトリ**に対応しました。プロジェクトが開発対象と + するリポジトリは `projects//project.yml` の `repos` 配列で指定し、すべてが同じ + コンテナの `/work` 配下へ clone されます。リポジトリごとに Git ホスト・オーナー・ + ブランチ・clone 先ディレクトリ名・`init.sh` の実行有無を指定できます。関連する複数 + リポジトリ (本体・ドキュメント・インフラ等) を 1 つの開発環境で横断的に扱えます。 + リポジトリが 2 件以上あるときは、全リポジトリを含む multi-root ワークスペース + `/work/<プロジェクト名>.code-workspace` を生成してエディタで開きます。 + 詳細は [project.yml リファレンス](docs/user/project-yml.md) を参照してください。 +- **プロジェクト設定を `env` から `project.yml` へ移しました (破壊的変更)。** + `GIT_USER` / `GIT_REPO` / `GIT_HOST` / `WORK_DIR` / `CONTAINER_SCALE` / + `DEVBASE_OPEN_EDITOR` は `project.yml` の `repos` / `work_dir` / `scale` / + `open_editor` に移行しました。`env` は「コンテナへ渡す環境変数」だけを持ちます。 + 配列を表現できない環境変数では複数リポジトリを書けないためです。 + `project.yml` を持たないプロジェクトは `devbase up` が移行手順を案内して停止します + (旧形式へ暗黙にフォールバックすると、移行漏れを検出できないため)。 + `devbase project scale N` の書き込み先も `project.yml` の `scale` になります。 + +> **Note:** リポジトリの clone は `entrypoint.sh` で行われ、これはイメージに焼き込まれます。 +> 適用には `devbase build --no-cache` によるベースイメージの再ビルドが必要です。 + ### Added +- **`devbase project migrate-config`** を追加しました。旧 `env` 形式のプロジェクト定義を + `project.yml` へ機械的に変換します。`--dry-run` で変換結果を確認でき、既存の + `project.yml` は上書きしないため何度実行しても同じ状態に収束します。 + 変換対象は上記 6 キーのみで、`ENABLE_SSH` などそれ以外は `env` に残ります。 - **tmux 内では `VSCODE_IPC_HOOK_CLI` が古くても VS Code を自動で開く**ようにしました。 tmux サーバーはセッション作成時の環境変数を保持し続けますが、`update-environment` に 登録した変数は attach のたびに更新されるため、**ペインのシェルは古い値・tmux の diff --git a/README.md b/README.md index c995ce0..d0d486f 100644 --- a/README.md +++ b/README.md @@ -144,6 +144,7 @@ devbaseのコマンドは4つのグループにまとめられています。 | [はじめに](docs/user/getting-started.md) | 前提条件、初回セットアップ、日常ワークフロー | | [CLIリファレンス](docs/user/cli-reference/README.md) | 全コマンドの構文・オプション・使用例（コマンドグループ別） | | [プラグインレジストリ](docs/user/plugin-registries.md) | 公開・社内レジストリの一覧と追加方法 | +| [project.yml リファレンス](docs/user/project-yml.md) | プロジェクト設定（複数リポジトリ・scale・エディタ） | | [環境変数ガイド](docs/user/environment-variables.md) | 3レベル構造、コレクター、ソース同期 | | [環境変数の export/import ガイド](docs/user/env-export-import.md) | バンドル形式・age 暗号化・S3 連携・merge/replace の運用 | | [コンテナ操作ガイド](docs/user/container-operations.md) | ライフサイクル、並行開発、ボリューム構造 | diff --git a/docs/README.md b/docs/README.md index b108925..2cf4ce5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -45,6 +45,7 @@ graph TD | [はじめに](user/getting-started.md) | 前提条件、初回セットアップ、日常ワークフロー | | [CLI リファレンス](user/cli-reference/README.md) | 全コマンドの構文・オプション・使用例 | | [プラグインレジストリ](user/plugin-registries.md) | 公開・社内レジストリの一覧と追加方法 | +| [project.yml リファレンス](user/project-yml.md) | プロジェクト設定（複数リポジトリ・scale・エディタ） | | [環境変数ガイド](user/environment-variables.md) | 3レベル構造、コレクター、ソース同期 | | [環境変数の暗号化](user/env-encryption.md) | 認証情報を暗号化して保存する / 鍵とチーム共有 / 平文へ戻す | | [コンテナ操作ガイド](user/container-operations.md) | ライフサイクル、並行開発、ボリューム構造 | @@ -101,6 +102,7 @@ docs/ │ │ ├── 04-plugin.md ← plugin グループ │ │ └── 05-snapshot.md ← snapshot グループ │ ├── plugin-registries.md ← プラグインレジストリ +│ ├── project-yml.md ← project.yml リファレンス │ ├── environment-variables.md ← 環境変数ガイド │ ├── env-encryption.md ← 環境変数の暗号化 │ ├── container-operations.md ← コンテナ操作ガイド @@ -128,6 +130,7 @@ docs/ | 環境変数を設定する | [環境変数ガイド](user/environment-variables.md#環境変数の操作) | | 認証情報を暗号化して保存する | [環境変数の暗号化](user/env-encryption.md) | | 複数コンテナで並行開発する | [コンテナ操作ガイド](user/container-operations.md#並行開発) | +| 1 つのコンテナで複数リポジトリを扱う | [project.yml リファレンス](user/project-yml.md#複数リポジトリ) | | データをバックアップ・復元する | [スナップショットガイド](user/snapshot-guide.md) | | エラーが発生した | [トラブルシューティング](user/troubleshooting.md) | | 旧 Orca 接続から移行する | [Orca 削除の移行ガイド](user/orca-removal-migration.md) | diff --git a/docs/developer/architecture.md b/docs/developer/architecture.md index 4e1ef27..963f3bb 100644 --- a/docs/developer/architecture.md +++ b/docs/developer/architecture.md @@ -139,6 +139,26 @@ flowchart LR `snapshot/manager.py` の `SnapshotManager` クラスが全機能を提供する。差分バックアップとフルバックアップに対応し、zstd 圧縮を使用する。 +### project/ -- プロジェクト設定 (project.yml) + +`projects//project.yml` を読み、コンテナとエディタが使える形へ変換する層。 +YAML の解釈をホスト側の Python に閉じ込めることで、コンテナ側 (`entrypoint.sh`) は +復号して 1 行ずつ clone するだけで済み、イメージへ YAML パーサ依存を持ち込まない。 + +| モジュール | 役割 | +|-----------|------| +| `config.py` | `project.yml` の読み込み・`defaults` 継承・検証・正規化 (`ProjectConfig` / `RepoSpec`)。clone プランの符号化 (`encode_repo_plan`) | +| `runtime.py` | コンテナへ渡す環境変数の組み立て (`DEVBASE_REPOS` / `DEVBASE_PRIMARY_DIR` / `DEVBASE_WORKSPACE*`)、multi-root ワークスペース JSON の生成、`scale` の読み書き | +| `migrate.py` | 旧 `env` 形式 (`GIT_USER` / `GIT_REPO` 等) から `project.yml` への変換 | + +```mermaid +flowchart LR + Y["project.yml"] --> C["config.py
検証・正規化"] + C --> R["runtime.py
環境変数へ"] + R --> Compose[".docker-compose.scale.yml
dev サービス"] + Compose --> E["entrypoint.sh
復号して clone"] +``` + ### その他 | ディレクトリ | 役割 | diff --git a/docs/plugin-dev/compose-yml-guidelines.md b/docs/plugin-dev/compose-yml-guidelines.md index 977b92a..4aa7065 100644 --- a/docs/plugin-dev/compose-yml-guidelines.md +++ b/docs/plugin-dev/compose-yml-guidelines.md @@ -71,10 +71,9 @@ flowchart TB G1["共通APIキー"] G2["共有設定値"] end - subgraph level2["レベル2: プロジェクト設定（env）"] - P1["GIT_USER / GIT_REPO"] - P2["WORK_DIR"] - P3["CONTAINER_SCALE"] + subgraph level2["レベル2: プロジェクト環境変数（env）"] + P1["ENABLE_SSH など"] + P2["アプリが読む変数"] end subgraph level3["レベル3: プロジェクト機密（.env）"] S1["プロジェクト固有のAPIキー"] @@ -90,7 +89,7 @@ flowchart TB | レベル | ファイル | Git管理 | 用途 | 例 | |--------|---------|---------|------|-----| | 1 | `${DEVBASE_ROOT}/.env` | No | 全プロジェクト共通の設定 | 共通APIキー | -| 2 | `env` | Yes | プロジェクト固有の設定 | `GIT_REPO`, `CONTAINER_SCALE` | +| 2 | `env` | Yes | コンテナへ渡すプロジェクト固有の環境変数 | `ENABLE_SSH` | | 3 | `.env` | No | プロジェクト固有の機密 | DB接続文字列、秘密鍵 | --- @@ -204,9 +203,9 @@ ports: 例: `CONTAINER_INDEX=1` の場合は `13000:3000`、`CONTAINER_INDEX=2` の場合は `23000:3000` -### 5.3 CONTAINER_SCALE の設定 +### 5.3 コンテナ数（scale）の設定 -`env` ファイルで `CONTAINER_SCALE` を設定すると、`devbase up` 実行時に `.docker-compose.scale.yml` が自動生成され、指定された数のコンテナが起動します。 +`project.yml` の `scale` を設定すると、`devbase up` 実行時に `.docker-compose.scale.yml` が自動生成され、指定された数のコンテナが起動します（既定: 2）。詳細は [project.yml リファレンス](../user/project-yml.md) を参照してください。 --- @@ -241,15 +240,18 @@ networks: external: true ``` -対応する `env` ファイル: +対応する `project.yml`: -```bash -GIT_USER=your-org -GIT_REPO=my-webapp -WORK_DIR=/work/$GIT_REPO -CONTAINER_SCALE=1 +```yaml +version: 1 +scale: 1 +repos: + - owner: your-org + repo: my-webapp ``` +`env` にはコンテナへ渡す環境変数だけを書きます（無くてもファイル自体は残します。`env_file` が参照するため）。 + ### 6.2 データベースを含む構成 基本構成に `db` サービスを追加し、`depends_on` で依存関係を定義します。 diff --git a/docs/plugin-dev/quickstart.md b/docs/plugin-dev/quickstart.md index e607daa..7084ee2 100644 --- a/docs/plugin-dev/quickstart.md +++ b/docs/plugin-dev/quickstart.md @@ -93,26 +93,56 @@ networks: > **補足:** compose.yml の記述ルール詳細は [compose.yml ガイドライン](compose-yml-guidelines.md) を参照してください。 -### 2.3 env ファイルの作成 +### 2.3 project.yml の作成 -`projects/my-project/env` を作成します。このファイルはGit管理対象です。 +`projects/my-project/project.yml` を作成します。このファイルはGit管理対象で、**プロジェクト設定の正**です。 -```bash -GIT_USER=your-github-user -GIT_REPO=my-repo -WORK_DIR=/work/$GIT_REPO -CONTAINER_SCALE=1 -# GitLab等GitHub以外のホストを使う場合: -# GIT_HOST=gitlab.com +```yaml +version: 1 +scale: 1 +repos: + - owner: your-github-user + repo: my-repo ``` -| 変数 | 説明 | +複数のリポジトリを 1 つのコンテナへチェックアウトできます。 + +```yaml +version: 1 +scale: 1 +defaults: + owner: your-github-user +repos: + - repo: my-app # 先頭が primary（ログイン直後の作業ディレクトリ） + - repo: my-app-docs + - repo: my-app-infra + host: gitlab.com # リポジトリごとに Git ホストを変えられる + owner: another-org + dir: infra # /work 配下の clone 先名（既定: repo 名） + branch: develop # clone 後にチェックアウトするブランチ + init: false # clone 後の ./init.sh を実行しない +``` + +主なキーは以下のとおりです。全項目は [project.yml リファレンス](../user/project-yml.md) を参照してください。 + +| キー | 説明 | |------|------| -| `GIT_USER` | Gitホストのユーザー名またはOrganization名 | -| `GIT_REPO` | リポジトリ名 | -| `GIT_HOST` | Gitホスト名（デフォルト: `github.com`）。GitLabの場合は `gitlab.com` を指定 | -| `WORK_DIR` | コンテナ内の作業ディレクトリ | -| `CONTAINER_SCALE` | 起動するコンテナ数（デフォルト: 2） | +| `version` | スキーマ版。現在は `1` | +| `repos[].owner` / `repos[].repo` | Git ホストのユーザー名（Organization 名）とリポジトリ名 | +| `repos[].host` | Git ホスト名（既定: `github.com`）。GitLab なら `gitlab.com` | +| `repos[].dir` / `branch` / `init` / `primary` | clone 先ディレクトリ名 / チェックアウトするブランチ / `init.sh` の実行有無 / 既定の作業リポジトリ | +| `scale` | 起動するコンテナ数（既定: 2） | +| `open_editor` | `devbase up` 後に VS Code を自動で開くか | + +### 2.3.1 env ファイル（任意） + +`projects/my-project/env` には、**コンテナへ渡す環境変数**だけを書きます（`ENABLE_SSH` など）。devbase 自身の設定は `project.yml` にあります。 + +```bash +ENABLE_SSH=true +``` + +`compose.yml` が `env_file: - env` で参照するため、**中身が無くてもファイルは残してください**（実在しないと compose が起動時に落ちます）。 ### 2.4 .env ファイル（任意） @@ -137,12 +167,10 @@ MY_SECRET_API_KEY=sk-xxxxxxxxxxxx # projects/my-project/pre-up set -e -# env から GIT_USER / GIT_REPO を取得 -source ./env - # build context に使うリポジトリが無ければ clone +# (pre-up はホスト側で動くフックなので、clone 先も URL もここに直接書く) if [ ! -d "./repo" ]; then - git clone "https://github.com/${GIT_USER}/${GIT_REPO}.git" repo + git clone "https://github.com/your-github-user/my-repo.git" repo fi ``` diff --git a/docs/plugin-dev/repo-backed-projects.md b/docs/plugin-dev/repo-backed-projects.md index ae1c61a..f5dd0d7 100644 --- a/docs/plugin-dev/repo-backed-projects.md +++ b/docs/plugin-dev/repo-backed-projects.md @@ -4,7 +4,7 @@ リファレンス実装は Laravel Sail ベースの `carmo-system-console` プラグインです。**このリポジトリには含まれません** — 社内向けの private プラグインレジストリで配布されており、`devbase plugin install` 後に `projects/carmo-system-console/`（`projects/` は `.gitignore` 対象）へ展開されます。アクセス権が無い場合でも、本書のコード断片と [チェックリスト](#7-チェックリスト新規に-repo-連携プロジェクトを作るとき) だけでパターンを再現できます。 -> **前提:** ライフサイクルフック自体の基本は [プラグイン開発クイックスタート](quickstart.md#25-ライフサイクルフック任意) を、共有ボリュームや `CONTAINER_SCALE` の一般論は [compose.yml ガイドライン](compose-yml-guidelines.md) と [コンテナ操作ガイド](../user/container-operations.md#並行開発) を参照してください。本書はそれらを組み合わせた「repo 連携」パターンに絞って説明します。 +> **前提:** ライフサイクルフック自体の基本は [プラグイン開発クイックスタート](quickstart.md#25-ライフサイクルフック任意) を、共有ボリュームや `scale` の一般論は [compose.yml ガイドライン](compose-yml-guidelines.md) と [コンテナ操作ガイド](../user/container-operations.md#並行開発) を参照してください。本書はそれらを組み合わせた「repo 連携」パターンに絞って説明します。 --- @@ -28,7 +28,7 @@ graph TD S["リモート git リポジトリ
(volareinc/app 等)"] -->|"pre-up ① clone/pull"| R["ホスト ./repo
(app のビルドコンテキスト)"] S3["S3
env/<env>.env"] -->|"pre-up ② 取得"| E["ホスト ./.env
(compose 変数展開用)"] - R -->|"pre-up ③ populate"| V["共有 work ボリューム
/work/<GIT_REPO>"] + R -->|"pre-up ③ populate"| V["共有 work ボリューム
/work/<リポジトリ名>"] E -->|"pre-up ④ 配置"| V V --> A["app コンテナ /work"] V --> N["nginx コンテナ /work:ro"] @@ -64,9 +64,9 @@ volumes: > **Note:** `pre-up` は子プロセスのため `export DEVBASE_WORK_VOLUME` しても後続の `docker compose up` へは伝播しません。`compose.yml` 側は `${DEVBASE_WORK_VOLUME:-devbase_work_${DEVBASE_INSTANCE_INDEX:-1}}` のフォールバック式で解決し、加えて `pre-up` が同じ値を `.env` に書き出すことで整合を取ります。 -### スケール前提: `CONTAINER_SCALE=1` +### スケール前提: `scale: 1` -**このパターンは scale=1（1 プロジェクト = 1 work ボリューム）を前提としています。** devbase の既定は `CONTAINER_SCALE=2` なので、プロジェクトの `env` に `CONTAINER_SCALE=1` を明示してください。 +**このパターンは scale=1（1 プロジェクト = 1 work ボリューム）を前提としています。** devbase の既定は `2` なので、プロジェクトの [`project.yml`](../user/project-yml.md) に `scale: 1` を明示してください。 現行実装では、scale>1 にすると「全コンテナが同一のソースツリーを共有する」という本パターンの前提が次の 2 点で崩れます。 @@ -78,7 +78,7 @@ volumes: - **`DEVBASE_WORK_VOLUME` で名前を分ける。** scale 生成は dev サービスの `/work` を `devbase_work_`（scale=1 なら常に `devbase_work_1`）へ無条件に差し替えます（`compose.yml` に `/work` マウントを書いていなくても追加されます）。`DEVBASE_WORK_VOLUME` が効くのは app / nginx など非 dev サービスだけなので、既定名以外を指定すると dev だけが別ボリュームを見る分裂状態になります。 - **プロジェクトディレクトリごと複製する。** work ボリュームは `COMPOSE_PROJECT_NAME` の接頭辞が付かない[グローバルな external ボリューム](#クリーンに作り直す再-populate)なので、複製先も同じ `devbase_work_1` を共有します。分離になりません。 -同一リポジトリを同時に複数環境で動かす必要がある場合は、Docker ホスト（`docker context`）そのものを分けてください。なお **別リポジトリ**の repo 連携プロジェクト同士は、populate 先が `/work/` とサブディレクトリで分かれるため、同じ work ボリュームを共有したまま共存できます。 +同一リポジトリを同時に複数環境で動かす必要がある場合は、Docker ホスト（`docker context`）そのものを分けてください。なお **別リポジトリ**の repo 連携プロジェクト同士は、populate 先が `/work/<リポジトリ名>` とサブディレクトリで分かれるため、同じ work ボリュームを共有したまま共存できます。 --- @@ -90,8 +90,8 @@ volumes: |---|------|------| | ① | `repo/` の clone / pull | 無ければ `git clone`、あれば `git pull --ff-only`（app ビルドコンテキストの最新化） | | ② | `.env` の取得 | S3 等から取得してホスト `./.env` に配置（`docker compose` の変数展開前に必要） | -| ③ | work ボリュームへ populate | `repo/` の内容を `/work/` へコピー | -| ④ | `.env` を work ボリュームへ配置 | Laravel 等のランタイムが `/work//.env` を参照するため | +| ③ | work ボリュームへ populate | `repo/` の内容を `/work/<リポジトリ名>` へコピー | +| ④ | `.env` を work ボリュームへ配置 | Laravel 等のランタイムが `/work/<リポジトリ名>/.env` を参照するため | ② を `deploy`（`up` 後フック）ではなく `pre-up` で行うのは、`compose.yml` の `MYSQL_DATABASE: ${DB_DATABASE:-...}` のような変数展開が `docker compose` パース時（＝ MySQL コンテナ初回起動前）に `.env` を要求するためです。`deploy` 段階では間に合わず、DB がデフォルト名で初期化されてしまいます。 @@ -101,7 +101,7 @@ volumes: **このパターンの肝は「初回だけ populate し、2 回目以降はコンテナ側に触れない」ことです。** -`pre-up` は work ボリューム上に `/work//.git` が存在するかどうかで populate 済みを判定し、済みの場合は ②③④ をスキップします。 +`pre-up` は work ボリューム上に `/work/<リポジトリ名>/.git` が存在するかどうかで populate 済みを判定し、済みの場合は ②③④ をスキップします。 | # | 処理 | 未populate（初回） | populate 済み（2回目以降） | |---|------|:---:|:---:| @@ -130,20 +130,20 @@ populate 済み以降、更新経路は次のように分かれます。 | 対象 | 場所 | 更新方法 | |------|------|---------| | ビルドコンテキスト | ホスト `./repo` | `pre-up` が毎回 `git pull`（自動） | -| 実行時ソース | work ボリューム `/work/` | **コンテナ内で手動 `git pull`** | -| 実行時 `.env` | work ボリューム `/work//.env` | コンテナ内で手動編集 | +| 実行時ソース | work ボリューム `/work/<リポジトリ名>` | **コンテナ内で手動 `git pull`** | +| 実行時 `.env` | work ボリューム `/work/<リポジトリ名>/.env` | コンテナ内で手動編集 | ```bash # 実行時ソースの更新（dev コンテナ内） -cd /work/ +cd /work/<リポジトリ名> git pull origin main ``` ### クリーンに作り直す（再 populate） -`.env` やソースを S3 / `repo/` の内容からやり直したい場合は、populate 済み判定に使われる `/work/` を消して、次回 `up` で populate を再実行させます。 +`.env` やソースを S3 / `repo/` の内容からやり直したい場合は、populate 済み判定に使われる `/work/<リポジトリ名>` を消して、次回 `up` で populate を再実行させます。 -> **Warning:** work ボリューム（既定 `devbase_work_1`）は `COMPOSE_PROJECT_NAME` の接頭辞が付かない **グローバルな external ボリューム**で、同じインスタンス index を使う **すべての devbase プロジェクトが共有**します。`docker volume rm` でボリュームごと消すと、停止中の別プロジェクトのソースや生成物まで巻き添えで失われます。プロジェクトの分離単位はボリュームではなく `/work/` サブディレクトリなので、**通常はサブディレクトリだけを削除**してください。 +> **Warning:** work ボリューム（既定 `devbase_work_1`）は `COMPOSE_PROJECT_NAME` の接頭辞が付かない **グローバルな external ボリューム**で、同じインスタンス index を使う **すべての devbase プロジェクトが共有**します。`docker volume rm` でボリュームごと消すと、停止中の別プロジェクトのソースや生成物まで巻き添えで失われます。プロジェクトの分離単位はボリュームではなく `/work/<リポジトリ名>` サブディレクトリなので、**通常はサブディレクトリだけを削除**してください。 **推奨: このプロジェクトのサブディレクトリだけを削除する** @@ -153,8 +153,8 @@ devbase down # 何が入っているか（＝他プロジェクトが同居していないか）を確認 docker run --rm -v devbase_work_1:/work alpine ls -la /work -# このプロジェクトのソースだけを削除（ は env の値） -docker run --rm -v devbase_work_1:/work alpine rm -rf /work/ +# このプロジェクトのソースだけを削除（<リポジトリ名> は project.yml の repos[].dir） +docker run --rm -v devbase_work_1:/work alpine rm -rf /work/<リポジトリ名> devbase up # pre-up が ②③④ を再実行 ``` @@ -191,12 +191,12 @@ devbase up ## 7. チェックリスト（新規に repo 連携プロジェクトを作るとき） -- [ ] `env` に `GIT_USER` / `GIT_REPO` を定義した -- [ ] `env` に `CONTAINER_SCALE=1` を明記した（既定は `2`。[スケール前提](#スケール前提-container_scale1) を参照） +- [ ] `project.yml` に `repos`（`owner` / `repo`）を定義した +- [ ] `project.yml` に `scale: 1` を明記した（既定は `2`。[スケール前提](#スケール前提-scale-1) を参照） - [ ] `compose.yml` で work ボリュームを `external: true` + `name: ${DEVBASE_WORK_VOLUME:-devbase_work_${DEVBASE_INSTANCE_INDEX:-1}}` で宣言した - [ ] app サービスの `build.context` をホスト `./repo` にした - [ ] `pre-up` で ①clone/pull → ②`.env`取得 → ③populate → ④`.env`配置 を実装した -- [ ] `pre-up` が `/work//.git` の有無で populate 済みを判定し、②③④ をスキップする +- [ ] `pre-up` が `/work/<リポジトリ名>/.git` の有無で populate 済みを判定し、②③④ をスキップする - [ ] populate 時の owner を `1000:1000`（コンテナ内ユーザー）に設定した - [ ] `storage/` / `vendor/` / `node_modules/` 等、初回のみ生成され上書きしたくないパスの扱いを決めた - [ ] README にソース・`.env` の更新運用（手動 pull / 再 populate）を記載した diff --git a/docs/user/cli-reference/02-project.md b/docs/user/cli-reference/02-project.md index 1f2ae9e..505edf8 100644 --- a/docs/user/cli-reference/02-project.md +++ b/docs/user/cli-reference/02-project.md @@ -52,7 +52,8 @@ devbase up [name] - 起動時にスナップショットを自動作成（新世代 or 差分追加） - 直近のスナップショット取得から既定 60 分以内のときはスキップします - 間隔は `DEVBASE_SNAPSHOT_MIN_INTERVAL_MINUTES` 環境変数で上書き可能（既定 60、`0` で無効化＝毎回取得、不正値は警告して既定値） -- `CONTAINER_SCALE` の値に基づいてコンテナ数を決定 +- `project.yml` の `scale` に基づいてコンテナ数を決定（既定: 2） +- `project.yml` の `repos` を clone プランへ正規化してコンテナへ渡す（コンテナ内で `/work` 配下へ clone される） - イメージの自動準備（`devbase up` は `devbase rebuild`＝`devbase build --expires=7` 相当を実行）: - `build:` 定義あり、イメージ未存在 → `devbase build` を自動実行 - `build:` 定義あり、イメージ存在 → プロジェクトイメージの作成日で再ビルドの要否を判定: @@ -157,6 +158,37 @@ devbase project scale 3 devbase project scale adminer 3 ``` +新しい値は `project.yml` の `scale` に書き戻されるため、次回の `devbase up` にも引き継がれます。 + +## `devbase project migrate-config` + +旧 `env` 形式（`GIT_USER` / `GIT_REPO` / `GIT_HOST` / `WORK_DIR` / `CONTAINER_SCALE` / +`DEVBASE_OPEN_EDITOR`）のプロジェクト定義を [`project.yml`](../project-yml.md) へ変換します。 + +``` +devbase project migrate-config [NAME ...] [--dry-run] [--projects-dir DIR] +``` + +| パラメータ | 必須 | 説明 | +|-----------|------|------| +| `NAME` | いいえ | 対象プロジェクト名（省略時は `projects/` 配下すべて） | +| `--dry-run` | いいえ | 生成される `project.yml` を表示するだけで書き換えない | +| `--projects-dir` | いいえ | 対象ディレクトリ（既定: `$DEVBASE_ROOT/projects`）。devbase へリンクしていないプラグインリポジトリ内の `projects/` を直接変換する場合に使う | + +```bash +# まず変換結果を確認する +devbase project migrate-config --dry-run + +# 変換を適用する +devbase project migrate-config +``` + +- 変換対象は上記キーのみで、`ENABLE_SSH` などそれ以外は `env` に残ります +- 既存の `project.yml` は上書きしません（手で複数リポジトリ構成へ整えたものを壊さないため）。 + `env` に残った旧キーの掃除だけを行うため、何度実行しても同じ状態になります +- `projects/` はプラグインリポジトリへのシンボリックリンクです。書き換わるのはリンク先の + 実体（＝定義の正）で、出力には実際に触れたパスが表示されます + ## `devbase project build` コンテナイメージをビルドします。キャッシュの扱いは 3 モードあります。 diff --git a/docs/user/container-operations.md b/docs/user/container-operations.md index efe84d0..b66c269 100644 --- a/docs/user/container-operations.md +++ b/docs/user/container-operations.md @@ -69,11 +69,14 @@ devbase は複数のコンテナを同時に起動し、並行開発を行うこ ### コンテナ数の設定 -プロジェクトの `env` ファイルで `CONTAINER_SCALE` を設定します。デフォルト値は `2` です。 - -```bash -# env ファイルで設定 -CONTAINER_SCALE=2 +プロジェクトの [`project.yml`](project-yml.md) で `scale` を設定します。デフォルト値は `2` です。 + +```yaml +version: 1 +scale: 2 +repos: + - owner: your-org + repo: my-repo ``` ### 動的スケーリング @@ -295,7 +298,7 @@ devbase status ## ベストプラクティス 1. **プロジェクト固有のファイルは `/work` に配置する** -- `/persistent/ai`（`~/.claude` 等の symlink 先・`~/share`）は全コンテナで共有されるため -2. **`CONTAINER_SCALE` は必要最小限に設定する** -- リソース消費を抑制 +2. **`scale` は必要最小限に設定する** -- リソース消費を抑制 3. **作業終了後は `devbase down` を実行する** -- 自動ローテーションでディスク容量を管理 4. **`devbase ps` で状態を確認してからログインする** -- 異常終了したコンテナへのログイン試行を避ける 5. **イメージのビルドは初回と更新時のみ** -- 変更がない場合はキャッシュが利用される diff --git a/docs/user/environment-variables.md b/docs/user/environment-variables.md index e0cd444..1308049 100644 --- a/docs/user/environment-variables.md +++ b/docs/user/environment-variables.md @@ -34,14 +34,19 @@ graph TD **プロジェクト設定 `env`（`projects/*/env`）** -プロジェクト固有の設定値を格納します。Git 管理対象のため、機密情報は含めないでください。 +コンテナへ渡すプロジェクト固有の環境変数を格納します。Git 管理対象のため、機密情報は含めないでください。 ```bash # env ファイルの例 -REPO_NAME=my-project -CONTAINER_SCALE=2 +ENABLE_SSH=true ``` +devbase 自身の設定（どのリポジトリを clone するか、コンテナ数、エディタの自動オープン）は +環境変数ではなく [`projects/*/project.yml`](project-yml.md) に書きます。`env` に +`GIT_USER` / `GIT_REPO` / `WORK_DIR` / `CONTAINER_SCALE` を書いても効果はありません。 + +`compose.yml` が `env_file: - env` で参照するため、中身が無くてもファイル自体は残してください。 + **プロジェクト機密 `.env`（`projects/*/.env`）** プロジェクト固有の機密情報を格納します。gitignore 対象のため、チームメンバーは個別に設定する必要があります。 @@ -140,15 +145,20 @@ devbase はホストマシンの認証情報を自動収集し、コンテナ内 ## `devbase up` 後のエディタ自動オープン -`devbase up` 完了後、dev コンテナへ接続した VS Code を自動で開けます（VS Code の「Attach to Running Container」を CLI から起動）。既定では `/work/$GIT_REPO` フォルダを開きます（`--folder-uri`）。`DEVBASE_WORKSPACE` を指定するとフォルダの代わりに `*.code-workspace` ワークスペースファイルを開きます（`--file-uri`）。 +`devbase up` 完了後、dev コンテナへ接続した VS Code を自動で開けます（VS Code の「Attach to Running Container」を CLI から起動）。 + +開く対象は [`project.yml`](project-yml.md) から決まります。 + +- リポジトリが 1 件: primary リポジトリのフォルダ（`--folder-uri`） +- リポジトリが 2 件以上: 全リポジトリを含む multi-root ワークスペース `/work/<プロジェクト名>.code-workspace`（`--file-uri`） -これらは `devbase env init` の収集対象外で、プロジェクトの `env` か `$DEVBASE_ROOT/.env` に手書きする devbase 動作設定です。 +自動オープンの有無は `project.yml` の `open_editor` が最優先で、未指定なら以下の env に従います。これらは `devbase env init` の収集対象外で、`$DEVBASE_ROOT/.env` かプロジェクトの `env` に手書きする devbase 動作設定です。 | キー | 説明 | |------|------| -| `DEVBASE_OPEN_EDITOR` | 真（`1`/`true`/`yes`/`on`）で `up` 後にエディタを開く（既定: OFF） | +| `DEVBASE_OPEN_EDITOR` | 真（`1`/`true`/`yes`/`on`）で `up` 後にエディタを開く（既定: OFF）。`project.yml` の `open_editor` が指定されていればそちらが優先 | | `DEVBASE_EDITOR` | 起動コマンド（既定: `code`）。`cursor` / `code-insiders` 等も可 | -| `DEVBASE_WORKSPACE` | 開く `*.code-workspace` ファイルの**コンテナ内絶対パス**（例 `/home/ubuntu/share/work/uttarov2-doc.workspace`）。指定時はフォルダではなくワークスペースを開く。未設定なら従来どおり `/work/$GIT_REPO` フォルダ。`~/share`（= 全コンテナ共有ボリューム `/persistent/ai/share` への symlink）配下に置けば全コンテナで共用可 | +| `DEVBASE_WORKSPACE` | 開く `*.code-workspace` ファイルの**コンテナ内絶対パス**を明示指定する（例 `/home/ubuntu/share/work/uttarov2-doc.workspace`）。複数リポジトリ構成では devbase が自動生成するため通常は不要。`~/share`（= 全コンテナ共有ボリューム `/persistent/ai/share` への symlink）配下に置けば全コンテナで共用可 | | `DEVBASE_OPEN_INDEX` | scale 時に開く dev インスタンス番号（既定: `1`） | | `DEVBASE_EDITOR_SSH_HOST` | Remote-SSH 跨ホスト構成での ssh-remote ホスト名（例 `mac2`）。**通常は `~/.vscode-server` から自動検出**され不要。検出が外れる場合のみ明示。下記「跨ホスト」参照 | | `DEVBASE_EDITOR_DOCKER_CONTEXT` | 跨ホスト時に ssh 先で使う docker context（既定: ホストの `docker context show`） | diff --git a/docs/user/project-yml.md b/docs/user/project-yml.md new file mode 100644 index 0000000..0677385 --- /dev/null +++ b/docs/user/project-yml.md @@ -0,0 +1,138 @@ +# project.yml リファレンス + +`projects//project.yml` は、1 つのプロジェクト（= 1 つの dev コンテナ群）が +**どのリポジトリを開発対象にするか**と、devbase 自身のふるまいを定義するファイルです。 +Git 管理対象で、プロジェクト設定の正です。 + +1 プロジェクトに複数のリポジトリを登録でき、すべてが同じコンテナの `/work` 配下へ +clone されます。関連する複数リポジトリ（本体・ドキュメント・インフラなど）を 1 つの +開発環境で横断的に扱うための仕組みです。 + +## 最小構成 + +```yaml +version: 1 +repos: + - owner: volareinc + repo: carmo +``` + +`devbase up` すると、コンテナ内の `/work/carmo` にリポジトリが clone され、 +ログイン直後の作業ディレクトリもそこになります。 + +## 複数リポジトリ + +```yaml +version: 1 +scale: 1 +open_editor: true + +defaults: + owner: uttaro-dev2 + +repos: + - repo: uttarov2 # 先頭が primary + host: gitlab.com # リポジトリごとにホストを変えられる + owner: uttaro_dev + dir: system # /work/system へ clone する + - repo: uttarov2-doc + - repo: uttarov2migration + branch: develop + init: false +``` + +リポジトリが 2 件以上あるとき、`devbase up` は全リポジトリを含む +**multi-root ワークスペース** `/work/<プロジェクト名>.code-workspace` を生成し、 +エディタはそれを開きます（1 件のときは primary リポジトリのフォルダを開きます）。 + +## キー一覧 + +### 最上位 + +| キー | 必須 | 既定値 | 説明 | +|------|------|--------|------| +| `version` | はい | -- | スキーマ版。現在は `1` | +| `repos` | はい | -- | clone するリポジトリの配列（1 件以上） | +| `defaults` | いいえ | -- | `repos` の各要素へ継承させる既定値（`host` / `owner` / `branch` / `init`） | +| `scale` | いいえ | `2` | 起動するコンテナ数。`devbase project scale N` はこの値を書き換える | +| `open_editor` | いいえ | -- | `devbase up` 後に VS Code を自動で開くか。未指定なら env `DEVBASE_OPEN_EDITOR` に従う | +| `work_dir` | いいえ | primary の `/work/` | エディタが開く既定フォルダを明示指定する | + +### `repos[]` + +| キー | 必須 | 既定値 | 説明 | +|------|------|--------|------| +| `owner` | はい | `defaults.owner` | Git ホストのユーザー名または Organization 名 | +| `repo` | はい | -- | リポジトリ名 | +| `host` | いいえ | `github.com` | Git ホスト名（例 `gitlab.com`） | +| `dir` | いいえ | `repo` と同じ | `/work` 直下の clone 先ディレクトリ名 | +| `branch` | いいえ | リポジトリの既定ブランチ | clone 直後にチェックアウトするブランチ | +| `init` | いいえ | `true` | clone 後にリポジトリ直下の `./init.sh` を実行するか | +| `primary` | いいえ | 先頭要素が `true` | ログイン直後の作業ディレクトリになるリポジトリ（1 件だけ指定可） | + +clone URL は `https:////.git` で組み立てられます。認証は +コンテナに渡された既存の Git 資格情報の仕組みに委ねます（`project.yml` に +資格情報は書きません）。 + +## 検証されること + +設定ミスを黙って無視せず、`devbase up` の時点でエラーにします。 + +- `owner` / `repo` が無い、`repos` が空 +- `dir` の重複（同じ `/work/` を 2 つのリポジトリが奪い合う） +- `primary: true` が 2 件以上 +- 未知のキー（`brunch: main` のような打ち間違いが「書いたのに効かない」形で表れないため） +- 値に空白・制御文字が混ざっている、`dir` が `/work` 直下から外れている + +## `env` との使い分け + +| 書く場所 | 内容 | 例 | +|---------|------|-----| +| `project.yml` | devbase 自身の設定 | リポジトリ、コンテナ数、エディタの自動オープン | +| `env` | コンテナへ渡す環境変数 | `ENABLE_SSH`、アプリが読む設定値 | +| `.env` | プロジェクト固有の機密 | API キー、DB 接続情報 | + +`compose.yml` が `env_file: - env` で参照するため、`env` は中身が無くても +ファイル自体を残してください（実在しないと compose が起動時に落ちます）。 + +## 旧 `env` 形式からの移行 + +`GIT_USER` / `GIT_REPO` / `GIT_HOST` / `WORK_DIR` / `CONTAINER_SCALE` / +`DEVBASE_OPEN_EDITOR` を `env` に書く旧形式は廃止されました。`project.yml` の無い +プロジェクトは `devbase up` が移行手順を案内して停止します。 + +変換は [`devbase project migrate-config`](cli-reference/02-project.md#devbase-project-migrate-config) +で行います。 + +```bash +devbase project migrate-config --dry-run # 変換結果を確認 +devbase project migrate-config # 適用 +``` + +| 旧 `env` のキー | 移行先 | +|----------------|--------| +| `GIT_USER` | `repos[].owner` | +| `GIT_REPO` | `repos[].repo` | +| `GIT_HOST` | `repos[].host` | +| `WORK_DIR` | `work_dir`（既定値と同じ場合は書きません） | +| `CONTAINER_SCALE` | `scale` | +| `DEVBASE_OPEN_EDITOR` | `open_editor` | + +## コンテナへの渡り方 + +`project.yml` を編集する人が意識する必要はありませんが、仕組みを知っておくと +トラブルシュートに役立ちます。 + +```mermaid +flowchart LR + Y["project.yml
(人が編集する正)"] -->|"devbase up がホスト側で正規化"| P["clone プラン
DEVBASE_REPOS (base64)"] + P -->|"compose の dev サービスへ"| C["コンテナ"] + C -->|"entrypoint が復号して clone"| W["/work/<dir> ×N"] +``` + +YAML の解釈はホスト側の Python に閉じています。コンテナ側は復号して 1 行ずつ +clone するだけなので、イメージへ YAML パーサを持ち込みません。 + +> **Note:** `entrypoint.sh` はイメージに焼き込まれます。devbase 本体を更新して +> clone のふるまいが変わった場合は、`devbase build --no-cache` でベースイメージを +> 再ビルドしないと反映されません。 From efb6a3a3b241fc610753ecc947724bc4fb948220 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Sun, 23 Aug 2026 01:43:32 +0900 Subject: [PATCH 2/9] =?UTF-8?q?docs:=20=E3=83=AC=E3=83=93=E3=83=A5?= =?UTF-8?q?=E3=83=BC=E6=8C=87=E6=91=98=E5=AF=BE=E5=BF=9C=20=E2=80=94=20?= =?UTF-8?q?=E3=82=A2=E3=83=B3=E3=82=AB=E3=83=BC=E5=88=87=E3=82=8C=E4=BF=AE?= =?UTF-8?q?=E6=AD=A3=E3=81=A8=20env=20=E3=83=95=E3=82=A1=E3=82=A4=E3=83=AB?= =?UTF-8?q?=E5=BF=85=E9=A0=88=E3=81=AE=E6=98=8E=E8=A8=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - repo-backed-projects.md: 見出し変更で切れた `#スケール前提-container_scale1` 参照 2 箇所を `#スケール前提-scale-1` に修正 - quickstart.md: `env` はファイル自体が必須（中身は任意）と見出しから分かるよう変更し、 最小構成のディレクトリツリーへ `project.yml` を追加 - project-yml.md: `env` ファイルが必須である旨を同じ表現に揃える Co-Authored-By: Claude Opus 5 (1M context) --- docs/plugin-dev/quickstart.md | 11 ++++++++--- docs/plugin-dev/repo-backed-projects.md | 4 ++-- docs/user/project-yml.md | 5 +++-- 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/plugin-dev/quickstart.md b/docs/plugin-dev/quickstart.md index 7084ee2..951f8ff 100644 --- a/docs/plugin-dev/quickstart.md +++ b/docs/plugin-dev/quickstart.md @@ -53,7 +53,8 @@ my-plugin/ └── projects/ └── my-project/ ├── compose.yml - └── env + ├── project.yml + └── env # 中身は任意だが、ファイルは必須 ``` ### 2.2 compose.yml の作成 @@ -134,7 +135,7 @@ repos: | `scale` | 起動するコンテナ数（既定: 2） | | `open_editor` | `devbase up` 後に VS Code を自動で開くか | -### 2.3.1 env ファイル（任意） +### 2.3.1 env ファイル（ファイルは必須・中身は任意） `projects/my-project/env` には、**コンテナへ渡す環境変数**だけを書きます（`ENABLE_SSH` など）。devbase 自身の設定は `project.yml` にあります。 @@ -142,7 +143,11 @@ repos: ENABLE_SSH=true ``` -`compose.yml` が `env_file: - env` で参照するため、**中身が無くてもファイルは残してください**（実在しないと compose が起動時に落ちます）。 +2.2 の `compose.yml` が `env_file: - env` で参照するため、**ファイルは必ず作成してください**（実在しないと `devbase up` が compose の起動時に失敗します）。渡したい環境変数が無ければ空ファイルで構いません。 + +```bash +touch projects/my-project/env +``` ### 2.4 .env ファイル（任意） diff --git a/docs/plugin-dev/repo-backed-projects.md b/docs/plugin-dev/repo-backed-projects.md index f5dd0d7..6a979db 100644 --- a/docs/plugin-dev/repo-backed-projects.md +++ b/docs/plugin-dev/repo-backed-projects.md @@ -182,8 +182,8 @@ devbase up |------|------|------| | `DEVBASE_REPO_PULL` | `1` | `0` にすると ①（`repo/` の `git pull`）を抑止。オフラインや意図的にビルドコンテキストを固定したいとき | | `DEVBASE_ENV_OVERWRITE` | `backup` | 未 populate 時の既存ホスト `.env` の扱い。`backup`（`.env.bak.` に退避して上書き）/ `skip`（既存があれば S3 取得しない）/ `force`（退避せず上書き） | -| `DEVBASE_WORK_VOLUME` | `devbase_work_` | `compose.yml` が参照する共有 work ボリューム名の明示指定。未指定なら `DEVBASE_INSTANCE_INDEX` から解決。ただし効くのは **app / nginx など非 dev サービスだけ**で、dev サービスの `/work` は scale 生成時に `devbase_work_` へ無条件に差し替えられます。dev から実行時ソースを触る本パターンでは **既定名のまま**にしてください（[スケール前提](#スケール前提-container_scale1) を参照） | -| `DEVBASE_INSTANCE_INDEX` | `1` | work ボリューム名のインデックス。**devbase 本体が渡すのは `deploy` フックに対してのみ**で、`pre-up` や `docker compose` のプロセス環境には渡りません。`compose.yml` の `${DEVBASE_INSTANCE_INDEX:-1}` は `.env` に書かれた値、無ければ `1` に解決されます（[スケール前提](#スケール前提-container_scale1) を参照） | +| `DEVBASE_WORK_VOLUME` | `devbase_work_` | `compose.yml` が参照する共有 work ボリューム名の明示指定。未指定なら `DEVBASE_INSTANCE_INDEX` から解決。ただし効くのは **app / nginx など非 dev サービスだけ**で、dev サービスの `/work` は scale 生成時に `devbase_work_` へ無条件に差し替えられます。dev から実行時ソースを触る本パターンでは **既定名のまま**にしてください（[スケール前提](#スケール前提-scale-1) を参照） | +| `DEVBASE_INSTANCE_INDEX` | `1` | work ボリューム名のインデックス。**devbase 本体が渡すのは `deploy` フックに対してのみ**で、`pre-up` や `docker compose` のプロセス環境には渡りません。`compose.yml` の `${DEVBASE_INSTANCE_INDEX:-1}` は `.env` に書かれた値、無ければ `1` に解決されます（[スケール前提](#スケール前提-scale-1) を参照） | > **Note:** `.env` の環境選択（例: `s3://.../env/local.env` の `local` 部分）など、S3 パスやプロファイルはプロジェクト固有の変数（例: `CARMO_ENV`）で制御することがあります。プロジェクトの `pre-up` 冒頭コメントを参照してください。 diff --git a/docs/user/project-yml.md b/docs/user/project-yml.md index 0677385..de5327e 100644 --- a/docs/user/project-yml.md +++ b/docs/user/project-yml.md @@ -92,8 +92,9 @@ clone URL は `https:////.git` で組み立てられます。 | `env` | コンテナへ渡す環境変数 | `ENABLE_SSH`、アプリが読む設定値 | | `.env` | プロジェクト固有の機密 | API キー、DB 接続情報 | -`compose.yml` が `env_file: - env` で参照するため、`env` は中身が無くても -ファイル自体を残してください（実在しないと compose が起動時に落ちます）。 +`compose.yml` が `env_file: - env` で参照するため、`env` は**ファイル自体が必須**です。 +渡したい環境変数が無ければ空ファイルで構いませんが、削除すると `devbase up` が +compose の起動時に失敗します。 ## 旧 `env` 形式からの移行 From 4e2b76e5b42f023ca2b8d5f6b2b57aeb1371eeef Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Sun, 23 Aug 2026 01:53:40 +0900 Subject: [PATCH 3/9] =?UTF-8?q?docs:=20DEVBASE=5FOPEN=5FEDITOR=20=E3=81=AF?= =?UTF-8?q?=20env=20init=20=E3=81=AE=E5=8F=8E=E9=9B=86=E5=AF=BE=E8=B1=A1?= =?UTF-8?q?=E3=81=A7=E3=81=82=E3=82=8B=E3=81=93=E3=81=A8=E3=82=92=E6=98=8E?= =?UTF-8?q?=E8=A8=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `devbase env init` の editor コレクター (lib/devbase/env/collectors/editor.py) が `DEVBASE_OPEN_EDITOR` を対話収集し、対話の既定は `1` (有効) である。 「収集対象外」「既定: OFF」という記述は実装と矛盾していたため、収集対象で あることと、OFF に倒れるのはキー自体が未設定のときだけである旨へ修正した。 Co-Authored-By: Claude Opus 5 (1M context) --- docs/user/environment-variables.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user/environment-variables.md b/docs/user/environment-variables.md index 1308049..9438133 100644 --- a/docs/user/environment-variables.md +++ b/docs/user/environment-variables.md @@ -152,11 +152,11 @@ devbase はホストマシンの認証情報を自動収集し、コンテナ内 - リポジトリが 1 件: primary リポジトリのフォルダ（`--folder-uri`） - リポジトリが 2 件以上: 全リポジトリを含む multi-root ワークスペース `/work/<プロジェクト名>.code-workspace`（`--file-uri`） -自動オープンの有無は `project.yml` の `open_editor` が最優先で、未指定なら以下の env に従います。これらは `devbase env init` の収集対象外で、`$DEVBASE_ROOT/.env` かプロジェクトの `env` に手書きする devbase 動作設定です。 +自動オープンの有無は `project.yml` の `open_editor` が最優先で、未指定なら以下の env に従います。このうち `DEVBASE_OPEN_EDITOR` だけは `devbase env init` の editor コレクターが対話収集し（対話の既定は `1` = 有効）、`$DEVBASE_ROOT/.env` に書き込まれます。残りは収集対象外で、`$DEVBASE_ROOT/.env` かプロジェクトの `env` に手書きする devbase 動作設定です。 | キー | 説明 | |------|------| -| `DEVBASE_OPEN_EDITOR` | 真（`1`/`true`/`yes`/`on`）で `up` 後にエディタを開く（既定: OFF）。`project.yml` の `open_editor` が指定されていればそちらが優先 | +| `DEVBASE_OPEN_EDITOR` | 真（`1`/`true`/`yes`/`on`）で `up` 後にエディタを開く。`devbase env init` の対話既定は `1`（有効）なので、init 済みの環境では通常 ON。キー自体が未設定のときのみ OFF に倒れる。`project.yml` の `open_editor` が指定されていればそちらが優先 | | `DEVBASE_EDITOR` | 起動コマンド（既定: `code`）。`cursor` / `code-insiders` 等も可 | | `DEVBASE_WORKSPACE` | 開く `*.code-workspace` ファイルの**コンテナ内絶対パス**を明示指定する（例 `/home/ubuntu/share/work/uttarov2-doc.workspace`）。複数リポジトリ構成では devbase が自動生成するため通常は不要。`~/share`（= 全コンテナ共有ボリューム `/persistent/ai/share` への symlink）配下に置けば全コンテナで共用可 | | `DEVBASE_OPEN_INDEX` | scale 時に開く dev インスタンス番号（既定: `1`） | From 7added423a08553bfab437c90e99126722747c39 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Sun, 23 Aug 2026 01:56:26 +0900 Subject: [PATCH 4/9] =?UTF-8?q?chore:=20=E3=83=97=E3=83=AD=E3=82=B8?= =?UTF-8?q?=E3=82=A7=E3=82=AF=E3=83=88=E8=A8=AD=E5=AE=9A=E3=81=AE=E7=A0=B4?= =?UTF-8?q?=E5=A3=8A=E7=9A=84=E5=A4=89=E6=9B=B4=E3=81=AB=E5=90=88=E3=82=8F?= =?UTF-8?q?=E3=81=9B=E3=81=A6=203.0.0=20=E3=81=B8=E4=B8=8A=E3=81=92?= =?UTF-8?q?=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit project.yml への移行はプロジェクト定義の互換性を壊すため、SemVer の major を上げる。プラグイン側は requires.devbase を ">=3.0.0" に更新して 非対応の devbase へインストールされないようにする必要がある (各 plugin リポジトリの PR で対応)。 CHANGELOG の [Unreleased] を [3.0.0] として確定し、ドキュメント中の バージョン表記も揃えた。 Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 5 +++++ docs/developer/architecture.md | 2 +- docs/plugin-dev/quickstart.md | 2 +- pyproject.toml | 2 +- 4 files changed, 8 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2d401fd..68767db 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,11 @@ ## [Unreleased] +## [3.0.0] - 2026-08-23 + +プロジェクト設定を `project.yml` へ移行する破壊的変更を含みます。プラグイン側の +プロジェクト定義も本バージョンに合わせた更新が必要です (`requires.devbase: ">=3.0.0"`)。 + ### Added - **tmux 内では `VSCODE_IPC_HOOK_CLI` が古くても VS Code を自動で開く**ようにしました。 tmux サーバーはセッション作成時の環境変数を保持し続けますが、`update-environment` に diff --git a/docs/developer/architecture.md b/docs/developer/architecture.md index 4e1ef27..dde4443 100644 --- a/docs/developer/architecture.md +++ b/docs/developer/architecture.md @@ -1,6 +1,6 @@ # devbase アーキテクチャ概要 -devbase v2.2.0 のアーキテクチャ設計と内部構造について説明する。 +devbase v3.0.0 のアーキテクチャ設計と内部構造について説明する。 ## 全体構成 diff --git a/docs/plugin-dev/quickstart.md b/docs/plugin-dev/quickstart.md index e607daa..da90bbe 100644 --- a/docs/plugin-dev/quickstart.md +++ b/docs/plugin-dev/quickstart.md @@ -6,7 +6,7 @@ devbase用のPluginを作成し、公開するまでの手順を解説します ## 前提条件 -- devbase 2.2.0 以上がインストール済み +- devbase 3.0.0 以上がインストール済み - Git がインストール済み - Docker / Docker Compose が利用可能 diff --git a/pyproject.toml b/pyproject.toml index 7a03a1e..8af0bd1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "devbase" -version = "2.2.0" +version = "3.0.0" description = "Docker-based Development Environment Manager" requires-python = ">=3.10" dependencies = [ From aef5c90beeeb334cb1dc3f5072b7beea4527ffaf Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Sun, 23 Aug 2026 02:02:42 +0900 Subject: [PATCH 5/9] =?UTF-8?q?fix:=20=E5=AE=9F=E8=A1=8C=E6=99=82=E7=89=88?= =?UTF-8?q?=E6=95=B0=E3=83=BBuv.lock=E3=83=BBCHANGELOG=20=E5=8F=82?= =?UTF-8?q?=E7=85=A7=E3=83=AA=E3=83=B3=E3=82=AF=E3=82=92=203.0.0=20?= =?UTF-8?q?=E3=81=B8=E5=90=8C=E6=9C=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit pyproject.toml だけを 3.0.0 にしたため、実行時の版数表示とロックファイルが 2.2.0 のまま取り残されていた。 - lib/devbase/__init__.py の __version__ を 3.0.0 へ (--version / status / export manifest の実体) - lib/devbase/cli.py, lib/devbase/commands/status.py の ImportError fallback も 同じ値へ同期 - uv.lock のローカルパッケージ版数を 3.0.0 へ (uv lock --check が通る状態に戻す) - CHANGELOG.md に [3.0.0] のリンク定義を追加し、[Unreleased] の比較開始点を v3.0.0 へ変更 - docs/user/env-export-import.md の manifest サンプルの devbase_version を 3.0.0 へ docs/user/plugin-registries.md の「devbase v2.2.0 以降」は当該仕様が導入された 版を指す履歴記述のため据え置く。 Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 3 ++- docs/user/env-export-import.md | 2 +- lib/devbase/__init__.py | 2 +- lib/devbase/cli.py | 2 +- lib/devbase/commands/status.py | 2 +- uv.lock | 2 +- 6 files changed, 7 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 68767db..e458ae1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -203,5 +203,6 @@ OSS 化に伴う初回リリース。devbase は本バージョンより `devbas ### Removed - 「公式レジストリ」固定の概念を廃止。各レジストリは対等な扱いとなる。 -[Unreleased]: https://github.com/devbasex/devbase/compare/v2.2.0...HEAD +[Unreleased]: https://github.com/devbasex/devbase/compare/v3.0.0...HEAD +[3.0.0]: https://github.com/devbasex/devbase/compare/v2.2.0...v3.0.0 [2.2.0]: https://github.com/devbasex/devbase/releases/tag/v2.2.0 diff --git a/docs/user/env-export-import.md b/docs/user/env-export-import.md index 8eb9ce2..5997562 100644 --- a/docs/user/env-export-import.md +++ b/docs/user/env-export-import.md @@ -74,7 +74,7 @@ env/projects//.env ```yaml version: 1 created_at: '2026-05-21T10:00:00+09:00' -devbase_version: 2.2.0 +devbase_version: 3.0.0 files: - path: env/global.env sha256: <64 文字 hex> diff --git a/lib/devbase/__init__.py b/lib/devbase/__init__.py index 24ca405..9eaa5dd 100644 --- a/lib/devbase/__init__.py +++ b/lib/devbase/__init__.py @@ -1,4 +1,4 @@ """devbase - Docker-based Development Environment Manager""" -__version__ = "2.2.0" +__version__ = "3.0.0" __author__ = "devbase team" diff --git a/lib/devbase/cli.py b/lib/devbase/cli.py index 1371120..747b8d1 100644 --- a/lib/devbase/cli.py +++ b/lib/devbase/cli.py @@ -14,7 +14,7 @@ try: from . import __version__ except ImportError: - __version__ = "2.2.0" + __version__ = "3.0.0" logger = get_logger("devbase.cli") diff --git a/lib/devbase/commands/status.py b/lib/devbase/commands/status.py index 55d8bb2..65d104e 100644 --- a/lib/devbase/commands/status.py +++ b/lib/devbase/commands/status.py @@ -10,7 +10,7 @@ try: from devbase import __version__ except ImportError: - __version__ = "2.2.0" + __version__ = "3.0.0" logger = get_logger(__name__) diff --git a/uv.lock b/uv.lock index 3e2a11d..b33e944 100644 --- a/uv.lock +++ b/uv.lock @@ -41,7 +41,7 @@ wheels = [ [[package]] name = "devbase" -version = "2.2.0" +version = "3.0.0" source = { virtual = "." } dependencies = [ { name = "boto3" }, From 5dbe870f0035bb0802b49ce17e774b07b28dd3b1 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Sun, 23 Aug 2026 02:03:37 +0900 Subject: [PATCH 6/9] =?UTF-8?q?docs:=20init.sh=20=E3=81=AE=E5=AE=9F?= =?UTF-8?q?=E8=A1=8C=E9=A0=BB=E5=BA=A6=E3=81=A8=20DEVBASE=5FWORKSPACE=20?= =?UTF-8?q?=E3=81=AE=E6=9C=89=E5=8A=B9=E7=AF=84=E5=9B=B2=E3=82=92=E5=AE=9F?= =?UTF-8?q?=E8=A3=85=E3=81=AB=E5=90=88=E3=82=8F=E3=81=9B=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - project.yml リファレンス: `init` は clone 直後だけでなくコンテナ起動の たびに `./init.sh` を実行することを明記し、`branch` (clone 直後のみ) との タイミング差の表と冪等性の注意を追加 - 環境変数: `DEVBASE_WORKSPACE` が効くのはリポジトリ 1 件の構成だけで、 2 件以上では自動生成した workspace を直接開くため上書きできない旨を明記 - container-operations / plugin-dev quickstart の関連記述も同じ挙動へ揃える Co-Authored-By: Claude Opus 5 (1M context) --- docs/plugin-dev/quickstart.md | 4 ++-- docs/user/container-operations.md | 2 +- docs/user/environment-variables.md | 2 +- docs/user/project-yml.md | 14 +++++++++++++- 4 files changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/plugin-dev/quickstart.md b/docs/plugin-dev/quickstart.md index 951f8ff..52c102a 100644 --- a/docs/plugin-dev/quickstart.md +++ b/docs/plugin-dev/quickstart.md @@ -121,7 +121,7 @@ repos: owner: another-org dir: infra # /work 配下の clone 先名（既定: repo 名） branch: develop # clone 後にチェックアウトするブランチ - init: false # clone 後の ./init.sh を実行しない + init: false # 起動のたびの ./init.sh 実行を無効化する ``` 主なキーは以下のとおりです。全項目は [project.yml リファレンス](../user/project-yml.md) を参照してください。 @@ -131,7 +131,7 @@ repos: | `version` | スキーマ版。現在は `1` | | `repos[].owner` / `repos[].repo` | Git ホストのユーザー名（Organization 名）とリポジトリ名 | | `repos[].host` | Git ホスト名（既定: `github.com`）。GitLab なら `gitlab.com` | -| `repos[].dir` / `branch` / `init` / `primary` | clone 先ディレクトリ名 / チェックアウトするブランチ / `init.sh` の実行有無 / 既定の作業リポジトリ | +| `repos[].dir` / `branch` / `init` / `primary` | clone 先ディレクトリ名 / チェックアウトするブランチ（clone 直後のみ） / `init.sh` の実行有無（起動のたびに実行。冪等に書くこと） / 既定の作業リポジトリ | | `scale` | 起動するコンテナ数（既定: 2） | | `open_editor` | `devbase up` 後に VS Code を自動で開くか | diff --git a/docs/user/container-operations.md b/docs/user/container-operations.md index b66c269..b140ec5 100644 --- a/docs/user/container-operations.md +++ b/docs/user/container-operations.md @@ -183,7 +183,7 @@ AI CLI ツールの設定や認証情報は、コンテナを再生成しても - `/persistent/ai` は全コンテナ共通の `devbase_home_ubuntu` ボリュームなので、**どのコンテナからも同じ実体**を参照します（例: `~/share` は全コンテナで共有）。 - symlink **対象外**のホーム配下ファイル（シェル履歴など）はコンテナ層に置かれ、再生成で失われます。永続化したいものは `/persistent/ai` 配下（= 上記 symlink 先）か `/work` に置いてください。 -- `share` 配下に置いた VS Code ワークスペースファイルは `DEVBASE_WORKSPACE` で開けます（[環境変数](environment-variables.md) 参照）。 +- `share` 配下に置いた VS Code ワークスペースファイルは `DEVBASE_WORKSPACE` で開けます（リポジトリ 1 件の構成のみ。[環境変数](environment-variables.md) 参照）。 > **Note:** symlink 対象は entrypoint にビルド時 `COPY` で焼き込まれます。エントリを増減した場合は > イメージの再ビルドが必要です（`devbase up` 単体では反映されない場合があります。[CLI リファレンス: project グループ](cli-reference/02-project.md#devbase-project-up) の `devbase project up` の注記参照）。 diff --git a/docs/user/environment-variables.md b/docs/user/environment-variables.md index 9438133..769dba2 100644 --- a/docs/user/environment-variables.md +++ b/docs/user/environment-variables.md @@ -158,7 +158,7 @@ devbase はホストマシンの認証情報を自動収集し、コンテナ内 |------|------| | `DEVBASE_OPEN_EDITOR` | 真（`1`/`true`/`yes`/`on`）で `up` 後にエディタを開く。`devbase env init` の対話既定は `1`（有効）なので、init 済みの環境では通常 ON。キー自体が未設定のときのみ OFF に倒れる。`project.yml` の `open_editor` が指定されていればそちらが優先 | | `DEVBASE_EDITOR` | 起動コマンド（既定: `code`）。`cursor` / `code-insiders` 等も可 | -| `DEVBASE_WORKSPACE` | 開く `*.code-workspace` ファイルの**コンテナ内絶対パス**を明示指定する（例 `/home/ubuntu/share/work/uttarov2-doc.workspace`）。複数リポジトリ構成では devbase が自動生成するため通常は不要。`~/share`（= 全コンテナ共有ボリューム `/persistent/ai/share` への symlink）配下に置けば全コンテナで共用可 | +| `DEVBASE_WORKSPACE` | 開く `*.code-workspace` ファイルの**コンテナ内絶対パス**を明示指定する（例 `/home/ubuntu/share/work/uttarov2-doc.workspace`）。**効くのはリポジトリ 1 件の構成だけ**です。2 件以上の構成では `devbase up` が自動生成した `/work/<プロジェクト名>.code-workspace` を直接開くため、この env を設定しても上書きできません。`~/share`（= 全コンテナ共有ボリューム `/persistent/ai/share` への symlink）配下に置けば全コンテナで共用可 | | `DEVBASE_OPEN_INDEX` | scale 時に開く dev インスタンス番号（既定: `1`） | | `DEVBASE_EDITOR_SSH_HOST` | Remote-SSH 跨ホスト構成での ssh-remote ホスト名（例 `mac2`）。**通常は `~/.vscode-server` から自動検出**され不要。検出が外れる場合のみ明示。下記「跨ホスト」参照 | | `DEVBASE_EDITOR_DOCKER_CONTEXT` | 跨ホスト時に ssh 先で使う docker context（既定: ホストの `docker context show`） | diff --git a/docs/user/project-yml.md b/docs/user/project-yml.md index de5327e..f91bcc9 100644 --- a/docs/user/project-yml.md +++ b/docs/user/project-yml.md @@ -67,13 +67,25 @@ repos: | `host` | いいえ | `github.com` | Git ホスト名（例 `gitlab.com`） | | `dir` | いいえ | `repo` と同じ | `/work` 直下の clone 先ディレクトリ名 | | `branch` | いいえ | リポジトリの既定ブランチ | clone 直後にチェックアウトするブランチ | -| `init` | いいえ | `true` | clone 後にリポジトリ直下の `./init.sh` を実行するか | +| `init` | いいえ | `true` | リポジトリ直下の `./init.sh` を実行するか。clone 直後だけでなく**コンテナ起動のたび**（既存 clone があっても）実行されます | | `primary` | いいえ | 先頭要素が `true` | ログイン直後の作業ディレクトリになるリポジトリ（1 件だけ指定可） | clone URL は `https:////.git` で組み立てられます。認証は コンテナに渡された既存の Git 資格情報の仕組みに委ねます（`project.yml` に 資格情報は書きません）。 +`branch` と `init` は実行タイミングが異なります。 + +| キー | 実行タイミング | 理由 | +|------|--------------|------| +| `branch` | **clone 直後の 1 回だけ** | 既存 clone にも毎回適用すると、コンテナ内で作業ブランチへ切り替えた状態が再起動のたびに引き戻されるため | +| `init` | **コンテナ起動のたび**（既存 clone があっても毎回） | 依存パッケージの再取得など、コンテナ再生成後にも必要な処理を置く場所のため | + +`init.sh` は毎回走るので、**何度実行しても同じ結果になる（冪等な）内容にしてください**。 +`git clone` や追記のような繰り返すと壊れる処理を書く場合は、スクリプト側で実行済みかを +判定してください。実行が重い・1 回だけでよい場合は `init: false` にして手動実行に切り替えます。 +なお `init.sh` の失敗は警告に留まり、他リポジトリの処理とコンテナ起動は続行されます。 + ## 検証されること 設定ミスを黙って無視せず、`devbase up` の時点でエラーにします。 From c48c3259b51e6d5afbf9ce127c5ef58fa582e887 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Sun, 23 Aug 2026 02:15:15 +0900 Subject: [PATCH 7/9] =?UTF-8?q?docs:=20=E8=AA=AD=E3=81=BF=E8=BE=BC?= =?UTF-8?q?=E3=81=BF=E9=A0=86=E5=BA=8F=E3=81=AE=E8=A1=A8=E3=81=8B=E3=82=89?= =?UTF-8?q?=E3=82=82=20env=20=E3=81=AE=E6=97=A7=E7=94=A8=E9=80=94=E3=82=92?= =?UTF-8?q?=E5=A4=96=E3=81=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit env の役割を「コンテナへ渡す環境変数」と書き換えたのに、直上の表だけ 「リポジトリ名・コンテナ数等」と旧仕様のままで矛盾していた。 Co-Authored-By: Claude Opus 5 (1M context) --- docs/user/environment-variables.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/environment-variables.md b/docs/user/environment-variables.md index 769dba2..cbe4a04 100644 --- a/docs/user/environment-variables.md +++ b/docs/user/environment-variables.md @@ -21,7 +21,7 @@ graph TD | 優先度 | レベル | ファイル | 用途 | Git 管理 | |-------|-------|---------|------|---------| | 1（低） | グローバル | `devbase/.env` | 共通 API キー・認証情報 | gitignore | -| 2 | プロジェクト設定 | `projects/*/env` | リポジトリ名・コンテナ数等 | 管理対象 | +| 2 | プロジェクト環境変数 | `projects/*/env` | コンテナへ渡すプロジェクト固有の環境変数（`ENABLE_SSH` 等） | 管理対象 | | 3（高） | プロジェクト機密 | `projects/*/.env` | プロジェクト固有の API キー | gitignore | > **Note:** 同じキーが複数のレベルに存在する場合、優先度が高いレベルの値が使用されます。例えば、グローバルの `AWS_PROFILE` をプロジェクトの `.env` で上書きすることで、プロジェクトごとに異なる AWS プロファイルを使用できます。 From 028175a26f4aa5f7cb826e336a5c0659bf009a24 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Sun, 23 Aug 2026 02:22:50 +0900 Subject: [PATCH 8/9] =?UTF-8?q?docs:=20plugin.yml=20=E3=81=AE=20requires.d?= =?UTF-8?q?evbase=20=E3=82=92=E5=AE=9F=E8=A3=85=E3=81=A9=E3=81=8A=E3=82=8A?= =?UTF-8?q?=E3=81=AB=E6=96=87=E6=9B=B8=E5=8C=96=E3=81=99=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CHANGELOG が 3.0.0 で requires.devbase: ">=3.0.0" への更新を求めているのに、 plugin.yml リファレンスに requires の記述が無く、プラグイン作者が何を書けばよいか たどれない状態だった (gemini round 2 の major 指摘)。 追記にあたって実装 (lib/devbase/plugin/syncer.py load_plugin_info) を確認したところ、 リファレンスとクイックスタートが載せていた plugins[] 配列 + projects[] 列挙の構造は どこからも読まれておらず、実際は plugin.yml が name / version / description / priority / requires.devbase を持つフラット形式で、プロジェクトは projects/ 配下の ディレクトリから自動検出される。旧構造のまま requires だけ足すと誤った位置を案内する ため、スキーマ記述を実装に合わせて訂正した上で追記している。 - plugin-yml-reference.md: 基本構造・フィールド一覧・使用例をフラット形式へ訂正。 requires (devbase 本体の最低バージョン。project.yml 形式は 3.0.0 以降でのみ読めるため ">=3.0.0" を指定する) と priority の詳細節を追加。プロジェクト自動検出を明記。 複数 Plugin を 1 リポジトリで配る場合は registry.yml を使う旨へ差し替え。 実在しないエラーメッセージを並べていたバリデーション表を実際の PluginError へ訂正。 - quickstart.md 1.2: plugin.yml サンプルをフラット形式 + requires.devbase へ更新。 検証: uv run pytest 1371 passed / 記載サンプルを load_plugin_info に通して requires_devbase='>=3.0.0' が取れることを確認。 --- docs/plugin-dev/plugin-yml-reference.md | 210 +++++++++++++----------- docs/plugin-dev/quickstart.md | 23 +-- 2 files changed, 124 insertions(+), 109 deletions(-) diff --git a/docs/plugin-dev/plugin-yml-reference.md b/docs/plugin-dev/plugin-yml-reference.md index 7e70c94..bcf0384 100644 --- a/docs/plugin-dev/plugin-yml-reference.md +++ b/docs/plugin-dev/plugin-yml-reference.md @@ -1,7 +1,7 @@ # plugin.yml リファレンス -`plugin.yml` はPluginリポジトリのルートに配置する設定ファイルです。 -Pluginのメタ情報とプロジェクト一覧を定義します。 +`plugin.yml` は Plugin ディレクトリのルートに配置する設定ファイルです。 +Plugin のメタ情報（名前・バージョン・必要な devbase 本体のバージョンなど）を定義します。 --- @@ -10,10 +10,13 @@ Pluginのメタ情報とプロジェクト一覧を定義します。 ```mermaid flowchart TB subgraph repo["Pluginリポジトリ"] - PY["plugin.yml"] - subgraph projects["projects/"] - P1["my-project-a/"] - P2["my-project-b/"] + RY["registry.yml
(リポジトリが持つPlugin一覧)"] + subgraph plugin["my-plugin/"] + PY["plugin.yml
(Pluginのメタ情報)"] + subgraph projects["projects/"] + P1["my-project-a/"] + P2["my-project-b/"] + end end end subgraph devbase["devbaseルート"] @@ -26,7 +29,7 @@ flowchart TB S2["my-project-b → plugins/my-plugin/projects/my-project-b"] end end - PY -->|"devbase plugin install"| PS + RY -->|"devbase plugin install"| PS repo -->|clone| IP IP -->|symlink| S1 IP -->|symlink| S2 @@ -37,45 +40,29 @@ flowchart TB ## 基本構造 ```yaml -plugins: - - name: my-plugin - version: 1.0.0 - description: "プラグインの説明" - projects: - - name: my-project-a - description: "プロジェクトAの説明" - path: projects/my-project-a - - name: my-project-b - description: "プロジェクトBの説明" - path: projects/my-project-b +name: my-plugin +version: "1.0.0" +description: "プラグインの説明" +requires: + devbase: ">=3.0.0" +priority: 0 ``` +Plugin が提供するプロジェクトは `projects/` 配下のディレクトリから**自動的に検出**されます。 +`plugin.yml` にプロジェクトを列挙する必要はありません。 + --- ## フィールド一覧 -### トップレベル - -| フィールド | 型 | 必須 | 説明 | -|-----------|-----|------|------| -| `plugins` | array | Yes | Plugin定義のリスト | - -### Plugin定義 (`plugins[*]`) - -| フィールド | 型 | 必須 | 説明 | -|-----------|-----|------|------| -| `name` | string | Yes | Plugin名 | -| `version` | string | Yes | セマンティックバージョン | -| `description` | string | No | Pluginの説明 | -| `projects` | array | Yes | プロジェクト定義のリスト | - -### プロジェクト定義 (`plugins[*].projects[*]`) - -| フィールド | 型 | 必須 | 説明 | -|-----------|-----|------|------| -| `name` | string | Yes | プロジェクト名 | -| `description` | string | No | プロジェクトの説明 | -| `path` | string | Yes | リポジトリルートからの相対パス | +| フィールド | 型 | 必須 | 既定値 | 説明 | +|-----------|-----|------|--------|------| +| `name` | string | Yes | ディレクトリ名 | Plugin名 | +| `version` | string | No | `0.1.0` | セマンティックバージョン | +| `description` | string | No | `""` | Pluginの説明 | +| `requires` | map | No | なし | 動作要件。現在は `devbase` キーのみ | +| `requires.devbase` | string | No | なし | 必要な devbase 本体の最低バージョン（例: `">=3.0.0"`） | +| `priority` | int | No | `0` | プロジェクト名が他Pluginと衝突したときの優先度。大きいほうが `projects/` を取る | --- @@ -122,41 +109,68 @@ version: 2.3.1 ### `description` -Pluginまたはプロジェクトの説明文です。 +Pluginの説明文です。 `devbase plugin list` で一覧表示されるため、簡潔に記述してください。 ```yaml description: "EC事業部のマイクロサービス群" ``` -### `projects` +### `requires` -Pluginに含まれるプロジェクトの一覧です。 -1つのPluginに複数のプロジェクトを含めることができます。 +この Plugin が動作するために必要な devbase 側の条件を書きます。 +現在使えるキーは `devbase`（本体の最低バージョン）だけです。 -### `projects[*].name`（プロジェクト名） +```yaml +requires: + devbase: ">=3.0.0" +``` -プロジェクトを一意に識別する名前です。 -インストール時に `projects//` としてシンボリックリンクが作成されます。 +| 値 | 意味 | +|----|------| +| `">=3.0.0"` | devbase 3.0.0 以上が必要 | +| 省略 | バージョン要件なし（どの版でも導入を試みる） | -**バリデーションルール:** +**devbase 3.0.0 以降のPluginは `">=3.0.0"` を指定してください。** +プロジェクト設定を `projects//project.yml` で記述する形式は devbase 3.0.0 で導入されたもので、 +2.x 系の devbase は `project.yml` を読めません。要件を書かないまま 2.x へ導入されると、 +インストールは成功するのに `devbase up` の段階で初めて失敗します。 -- Plugin名と同様の命名規則 -- devbase全体で一意であること（他のPluginのプロジェクト名と重複不可） +> `requires.devbase` を上げるのは、**Plugin が `project.yml` 形式へ移行したタイミング**です。 +> 本体の版数と一緒に自動では上がりません。 -### `projects[*].path` +### `priority` -リポジトリルートからの相対パスで、プロジェクトディレクトリの位置を指定します。 +同じ名前のプロジェクトを複数のPluginが提供したときに、どちらが `projects/` の +シンボリックリンクを取るかを決める整数です（既定 `0`、大きいほうが勝ち）。 +負けた側は `projects/.--` の形でリンクされ、どちらも利用できます。 ```yaml -path: projects/my-project +priority: 10 ``` -**注意事項:** +### プロジェクトの検出 -- パスの先頭に `/` を付けない（相対パスで記述する） -- 指定したディレクトリに `compose.yml` が存在すること -- 慣例として `projects/` ディレクトリ配下に配置する +`plugin.yml` にプロジェクト一覧は書きません。Plugin ディレクトリ直下の `projects/` にある +ディレクトリ（`.` で始まるものを除く）がそのままプロジェクトとして扱われ、インストール時に +devbase ルートの `projects//` へシンボリックリンクが作成されます。 + +``` +my-plugin/ +├── plugin.yml +└── projects/ + ├── my-project-a/ -> projects/my-project-a として公開される + │ ├── compose.yml + │ ├── project.yml + │ └── env + └── my-project-b/ + ├── compose.yml + ├── project.yml + └── env +``` + +各プロジェクトディレクトリの中身は +[クイックスタート](quickstart.md) と [project.yml リファレンス](../user/project-yml.md) を参照してください。 --- @@ -167,14 +181,11 @@ path: projects/my-project 最もシンプルな構成です。 ```yaml -plugins: - - name: my-api - version: 1.0.0 - description: "APIサーバー開発環境" - projects: - - name: my-api - description: "APIサーバー" - path: projects/my-api +name: my-api +version: "1.0.0" +description: "APIサーバー開発環境" +requires: + devbase: ">=3.0.0" ``` ディレクトリ構造: @@ -185,6 +196,7 @@ my-api/ └── projects/ └── my-api/ ├── compose.yml + ├── project.yml └── env ``` @@ -193,20 +205,11 @@ my-api/ 関連するプロジェクトをまとめて管理する場合に使います。 ```yaml -plugins: - - name: ecommerce - version: 2.1.0 - description: "ECサイト開発環境一式" - projects: - - name: ec-frontend - description: "フロントエンド（Next.js）" - path: projects/ec-frontend - - name: ec-backend - description: "バックエンドAPI（Go）" - path: projects/ec-backend - - name: ec-admin - description: "管理画面（Laravel）" - path: projects/ec-admin +name: ecommerce +version: "2.1.0" +description: "ECサイト開発環境一式" +requires: + devbase: ">=3.0.0" ``` ディレクトリ構造: @@ -217,37 +220,47 @@ ecommerce/ └── projects/ ├── ec-frontend/ │ ├── compose.yml + │ ├── project.yml │ └── env ├── ec-backend/ │ ├── compose.yml + │ ├── project.yml │ └── env └── ec-admin/ ├── compose.yml + ├── project.yml └── env ``` ### 1リポジトリに複数Pluginを含む場合 -`plugins` 配列に複数のPlugin定義を記述します。 -チーム横断で1つのリポジトリを共有する場合に使えます。 +`plugin.yml` は Plugin ごとに 1 ファイルです。1 つのリポジトリで複数の Plugin を配布する場合は、 +Plugin ごとにディレクトリを分けてそれぞれに `plugin.yml` を置き、リポジトリルートの +`registry.yml` に一覧を記述します。 + +``` +my-registry/ +├── registry.yml +├── team-alpha/ +│ ├── plugin.yml +│ └── projects/alpha-service/ +└── team-beta/ + ├── plugin.yml + └── projects/beta-service/ +``` + +`registry.yml`: ```yaml +name: my-registry +description: "社内レジストリ" plugins: - name: team-alpha - version: 1.0.0 + path: team-alpha description: "Alphaチームのプロジェクト" - projects: - - name: alpha-service - description: "Alphaチームのサービス" - path: projects/alpha-service - - name: team-beta - version: 1.2.0 + path: team-beta description: "Betaチームのプロジェクト" - projects: - - name: beta-service - description: "Betaチームのサービス" - path: projects/beta-service ``` --- @@ -258,7 +271,7 @@ devbaseには似た名前の2つのファイルがあります。混同しない | 項目 | plugin.yml | plugins.yml | |------|-----------|-------------| -| 配置場所 | Pluginリポジトリのルート | devbaseルートディレクトリ | +| 配置場所 | Pluginディレクトリのルート | devbaseルートディレクトリ | | 管理者 | Plugin開発者 | devbase（自動管理） | | 用途 | Pluginの定義・メタ情報 | インストール済みPluginのレジストリ | | Git管理 | Plugin側のリポジトリで管理 | devbase側のリポジトリで管理 | @@ -290,17 +303,16 @@ plugins: ## バリデーション -`plugin.yml` は `devbase plugin install` 実行時に自動的にバリデーションされます。 +`devbase plugin install` はリポジトリを clone したあと `registry.yml` と `plugin.yml` を読み込みます。 ### よくあるエラーと対処 | エラーメッセージ | 原因 | 対処 | |----------------|------|------| -| `Invalid plugin name` | 命名規則違反 | 英小文字・数字・ハイフンのみ使用 | -| `Invalid version format` | SemVer形式でない | `MAJOR.MINOR.PATCH` 形式に修正 | -| `Project directory not found` | pathが不正 | ディレクトリの存在を確認 | -| `compose.yml not found` | compose.ymlが未配置 | 指定ディレクトリに配置 | -| `Duplicate project name` | プロジェクト名が重複 | 一意な名前に変更 | +| `Failed to parse .../plugin.yml` | YAML の構文エラー | インデント・引用符を確認 | +| `No registry.yml found in repository` | リポジトリルートに `registry.yml` が無い | リポジトリルートに配置する | +| `Plugin '' not found in ` | `registry.yml` に該当 Plugin の記載が無い | `plugins[*].name` を確認 | +| `Plugin directory not found: ` | `registry.yml` の `path` が実在しない | `path` とディレクトリ名を突き合わせる | --- diff --git a/docs/plugin-dev/quickstart.md b/docs/plugin-dev/quickstart.md index 99b8828..db45c53 100644 --- a/docs/plugin-dev/quickstart.md +++ b/docs/plugin-dev/quickstart.md @@ -23,20 +23,23 @@ git init ### 1.2 plugin.yml の配置 -リポジトリのルートに `plugin.yml` を作成します。 -このファイルはPluginのメタ情報とプロジェクト一覧を定義します。 +リポジトリのルート（Plugin ディレクトリのルート）に `plugin.yml` を作成します。 +このファイルは Plugin のメタ情報を定義します。 ```yaml -plugins: - - name: my-plugin - version: 1.0.0 - description: "サンプルプラグイン" - projects: - - name: my-project - description: "サンプルプロジェクト" - path: projects/my-project +name: my-plugin +version: "1.0.0" +description: "サンプルプラグイン" +requires: + devbase: ">=3.0.0" +priority: 0 ``` +**ポイント:** + +- プロジェクトは `projects/` 配下のディレクトリから自動的に検出されます。`plugin.yml` に一覧を書く必要はありません。 +- `requires.devbase` には **この Plugin が動作する devbase 本体の最低バージョン**を書きます。`project.yml` 形式のプロジェクト定義は devbase 3.0.0 以降でしか読めないため、`project.yml` を持つ Plugin（= 本手順で作るもの）は必ず `">=3.0.0"` を指定してください。 + > **補足:** `plugin.yml` のフォーマット詳細は [plugin.yml リファレンス](plugin-yml-reference.md) を参照してください。 --- From 2165ad6e671a8a4facac7d6a8c4eaaa62ded0f43 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Sun, 23 Aug 2026 02:24:20 +0900 Subject: [PATCH 9/9] =?UTF-8?q?docs:=20plugin.yml=20=E3=81=AE=20name/versi?= =?UTF-8?q?on=20=E8=A8=98=E8=BF=B0=E3=82=92=E5=AE=9F=E8=A3=85=E3=81=AE?= =?UTF-8?q?=E6=8C=99=E5=8B=95=E3=81=B8=E6=8F=83=E3=81=88=E3=82=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - name: 強制されない命名規則を「バリデーションルール」と書いていたため 「命名規則（推奨）」へ改め、省略時はディレクトリ名になることを追記 - version: サンプルの引用符の有無を基本構造の例と統一 --- docs/plugin-dev/plugin-yml-reference.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/plugin-dev/plugin-yml-reference.md b/docs/plugin-dev/plugin-yml-reference.md index bcf0384..88b52fd 100644 --- a/docs/plugin-dev/plugin-yml-reference.md +++ b/docs/plugin-dev/plugin-yml-reference.md @@ -70,9 +70,10 @@ Plugin が提供するプロジェクトは `projects/` 配下のディレクト ### `name`（Plugin名） -Pluginを一意に識別する名前です。 +Pluginを一意に識別する名前です。省略するとディレクトリ名が使われますが、 +`registry.yml` の `plugins[*].name` と食い違うと追跡しにくいため明示してください。 -**バリデーションルール:** +**命名規則（推奨）:** - 使用可能文字: 英小文字、数字、ハイフン（`a-z`, `0-9`, `-`） - 先頭はアルファベット @@ -97,8 +98,8 @@ name: a # 2文字未満 **フォーマット:** `MAJOR.MINOR.PATCH` ```yaml -version: 1.0.0 -version: 2.3.1 +version: "1.0.0" +version: "2.3.1" ``` | 要素 | 意味 | インクリメントするとき |