docs(runtimes): driver TOML examples omit [openshell] version = 2 and fail preflight
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
評価
- 難易度
- 1/5
- 見積もり時間
- 1〜3時間
- 初心者へのやさしさ
- 88/100
- issue の種類
- ドキュメント
- 明瞭さ
- 明確に書かれている
- 活発さ
- 活発
調査の方向性
docs/how-it-works/sandboxes/runtimes.mdx を開き、その Docker、Podman、MicroVM のスニペットを configuration.mdx のスキーマ例と比較してください。ローカル環境が利用可能な場合は、openshell-gateway config preflight を使って記載されている再現手順を実行してください。各例が自己完結して [openshell] / version = 2 を含むか、ページが最初の例より前にその要件を明確に記載していれば完了です。
索引モデルが issue の本文から書いたものです。
説明
User Story
As an operator configuring a compute driver from the Runtimes documentation, I want the TOML snippets there to be valid on their own, so that copying one into a fresh gateway.toml doesn't stop the gateway from starting.
Problem Statement
The Docker, Podman, and MicroVM sections of docs/how-it-works/sandboxes/runtimes.mdx show snippets like this:
[openshell.gateway]
compute_driver = "docker"
[openshell.drivers.docker]
socket_path = "/var/run/docker.sock"
Put into a new ~/.config/openshell/gateway.toml (the Linux package installs none), this makes the service fail at ExecStartPre=openshell-gateway config preflight:
gateway config preflight failed: ... category=missing_version detected_version=missing;
the file was preserved unchanged; migrate it before restarting the gateway
The snippets omit [openshell] / version = 2, which configuration.mdx shows but runtimes.mdx doesn't.
Impact / Why This Matters
The error tells the user to follow the schema v2 migration steps. That's confusing for someone who never had a v1 file, and it isn't obvious that the documented snippet itself is incomplete. The gateway stays down until they find the missing key.
Acceptance Criteria
- The TOML examples in
runtimes.mdxinclude[openshell]/version = 2, or the page states once, before the first example, that every file needs it. - Optional: when a file has only v2-shaped tables and no version key, the preflight message suggests adding
[openshell] version = 2rather than pointing to a migration.
Reproduction Steps
- Linux install with no existing
~/.config/openshell/gateway.toml. - Copy the Docker driver snippet from
runtimes.mdxinto that file. - Run
openshell-gateway config preflight. It fails withmissing_version.
Environment
- OpenShell 0.1.2, gateway as a systemd user service (Debian package layout)
- 主要言語
- Rust
- スター
- 8.7k
- フォーク
- 1.3k
- 平均マージ
- 1日 21時間
- マージ済み PR（30日）
- 344
環境構築
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
NVIDIA/OpenShell のほかの issue
-
state:triage-needed
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
メンテナーはふだん 1 日以内に返信
-
state:triage-needed
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
メンテナーはふだん 1 日以内に返信
-
area:docs
難易度 1/5 1時間未満 初心者へのやさしさ 88/100
メンテナーはふだん 1 日以内に返信
-
state:triage-needed
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
NVIDIA/OpenShell#3400 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
area:cli state:validated
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
NVIDIA/OpenShell#2888 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
NVIDIA/OpenShell の issue をすべて見る
似ている issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 88/100
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
メンテナーはふだん 3 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 76/100
Automattic/harper#4503 ·
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1時間未満 初心者へのやさしさ 92/100
メンテナーはふだん 2 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 84/100