Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

docs(runtimes): driver TOML examples omit [openshell] version = 2 and fail preflight

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#3,881 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
1/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
88/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Lĩnh vực
documentation

Hướng nghiên cứu

Mở docs/how-it-works/sandboxes/runtimes.mdx và so sánh các đoạn mã Docker, Podman và MicroVM trong đó với ví dụ schema trong configuration.mdx. Chạy quy trình tái hiện được ghi trong tài liệu bằng openshell-gateway config preflight nếu môi trường cục bộ khả dụng. Hoàn tất khi mỗi ví dụ đều tự chứa và có [openshell] / version = 2, hoặc khi trang nêu rõ yêu cầu đó trước ví dụ đầu tiên.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

state:triage-needed
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.mdx include [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 = 2 rather than pointing to a migration.
Reproduction Steps
  1. Linux install with no existing ~/.config/openshell/gateway.toml.
  2. Copy the Docker driver snippet from runtimes.mdx into that file.
  3. Run openshell-gateway config preflight. It fails with missing_version.
Environment
  • OpenShell 0.1.2, gateway as a systemd user service (Debian package layout)
Ngôn ngữ chính
Rust
Star
13.2k
Fork
1.6k
Merge trung bình
1 ngày 23 giờ
Pull request đã merge (30 ngày)
355

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của NVIDIA/OpenShell

Tất cả issue của NVIDIA/OpenShell

Issue tương tự

Thêm issue về Rust

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.