From d3f44fd15980d07f4de448445d09c87db974f6be Mon Sep 17 00:00:00 2001 From: Shxiao Date: Wed, 23 Sep 2026 08:47:36 +0900 Subject: [PATCH] docs(contributing): describe make docker-init as the sandbox-image pull it is (#5742) `CONTRIBUTING.md` documents `make docker-init` as "Build the custom k3s image (with pre-cached sandbox image)" and lists building Docker images, installing frontend/backend dependencies, and sharing the pnpm cache as its effects. None of that is what the target does: `Makefile`'s `docker-init` runs `scripts/docker.sh init`, which only checks `docker images` and runs `docker pull` for the all-in-one sandbox image (skipping even that in local sandbox mode). It never calls `docker build`, and no k3s image exists anywhere in the repo. The root Makefile's own help text already says "make docker-init - Pull the sandbox image". The same misconception makes the registry-override note wrong: `UV_INDEX_URL` and `NPM_REGISTRY` are consumed as build args by `backend/Dockerfile` and `frontend/Dockerfile`, i.e. during the `docker compose up --build` that `make docker-start` performs, so they cannot affect a pull-only target. Correct the setup step, the command comment, and the registry note. No code change. Verified against the checkout: - `Select-String -Path scripts/docker.sh -Pattern 'docker build|docker pull'` -> only `docker pull "$SANDBOX_IMAGE"` (line 281); no `docker build` - `Select-String -Path Makefile -Pattern 'docker-init'` -> line 57 help text "Pull the sandbox image"; line 187 target -> `scripts/docker.sh init` - `Select-String -Path backend/Dockerfile,frontend/Dockerfile -Pattern 'UV_INDEX_URL|NPM_REGISTRY'` -> both declared as build ARGs - `backend/tests/test_client_live_policy.py::test_documentation_matches_live_test_commands` (the only test that reads CONTRIBUTING.md) still passes; it asserts "make test-live", the live opt-in variable, and "API", none of which this touches. Co-authored-by: Shxiao101 --- CONTRIBUTING.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 04a36792a..0205c6154 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -37,11 +37,9 @@ Docker provides a consistent, isolated environment with all dependencies pre-con ```bash make docker-init ``` - This will: - - Build Docker images - - Install frontend dependencies (pnpm) - - Install backend dependencies (uv) - - Share pnpm cache with host for faster builds + This pulls the sandbox image that the container sandbox modes run, so the + first sandbox container does not wait on the download. It is a no-op in + local sandbox mode (the default), which needs no image. 3. **Start development services**: ```bash @@ -86,7 +84,7 @@ Docker provides a consistent, isolated environment with all dependencies pre-con #### Docker Commands ```bash -# Build the custom k3s image (with pre-cached sandbox image) +# Pull the sandbox image used by the container sandbox modes make docker-init # Start Docker services (mode-aware, localhost:2026) make docker-start @@ -100,7 +98,7 @@ make docker-logs-frontend make docker-logs-gateway ``` -If Docker builds are slow in your network, you can override the default package registries before running `make docker-init` or `make docker-start`: +If Docker builds are slow in your network, you can override the default package registries before running `make docker-start`: ```bash export UV_INDEX_URL=https://pypi.org/simple