Run all tasks through docs-toolbox via build.sh - #55
Conversation
Make build.sh the single entry point for every repository task and run each task inside the docs-toolbox container image by default, with a documented local fallback when no container engine is available. - build.sh: dispatcher with validate, generate, test, test-ruby, test-js, adapters, check-adapters, build, presentation, all, clean, and help; container-wraps each task and falls back to local. Default image bumped to docs-toolbox v1.3.1 (which now ships Node.js). - CI (validate.yml, publish-docs.yml): drop setup-ruby/setup-node and run ./build.sh tasks so CI uses the same image as local runs. - Docs: add a "Running tasks" section with a task table; rewrite the Validation, Tests, and generation instructions to show ./build.sh first with the local command as fallback; update architecture-core, honey-for-devs, the arc42 local-and-ci deployment doc, and the bdd-specification verification note accordingly. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Run tasks against the docs-toolbox `latest` tag instead of a pinned version, so the repository picks up toolbox updates without a manual bump. Applies to both build.sh and scripts/render-presentation.sh. Override with DOCS_TOOLBOX_IMAGE when a pinned image is required. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
ReviewDie Grundidee ist richtig und die CI ist grün, aber ich würde den PR noch nicht mergen. 1. Blocking:
|
Apply PR #55 review feedback: - Reproducibility: pin the default image to docs-toolbox:v1.3.1 in both build.sh and scripts/render-presentation.sh instead of :latest, so the same commit always runs against the same toolchain. Override with DOCS_TOOLBOX_IMAGE (e.g. a digest) when needed. - File ownership: run the container with user mapping so generated files are not root-owned on native Linux — `--user $(id -u):$(id -g)` plus a writable HOME on Docker, `--userns=keep-id` on rootless Podman. Applies to build.sh and render-presentation.sh. - Explicit execution modes: container mode is the reproducible default; DOCS_TOOLBOX_LOCAL=1 opts into the host toolchain. Without a container engine and without that flag, tasks now abort instead of silently running locally. - Remove the redundant validate pass from `all` (build already validates via generate); `all` now runs test, check-adapters, and build. - Document the modes, pinning, ownership mapping, and abort behaviour in the README and the arc42 local-and-ci deployment doc. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
|
Danke für das Review — alle vier Punkte sind in 1. Blocking — Pinning statt 2. Blocking — Datei-Ownership. Der Container wird jetzt engine-spezifisch mit User-Mapping gestartet:
Gilt für 3. Major — expliziter Lokal-Modus. Container-Modus ist der reproduzierbare Default. 4. Minor — Verifiziert lokal (Podman keep-id): validate/test grün, Ownership korrekt, Lokal-Modus und Abort-Pfad wie erwartet; CI grün gegen |
dieterbaier
left a comment
dieterbaier
left a comment
There was a problem hiding this comment.
Re-review completed: the previously raised issues are resolved.
- The docs-toolbox image is now pinned to
v1.3.1in bothbuild.shandscripts/render-presentation.sh. - Docker and Podman now map file ownership appropriately and provide a writable
HOME, avoiding root-owned generated files on native Linux. - Local execution through
build.shis now explicit viaDOCS_TOOLBOX_LOCAL=1; without a running engine, the reproducible default mode fails clearly instead of silently falling back. - The redundant validation pass in
allwas removed. - CI is green for the current head.
One tiny non-blocking consistency note: scripts/render-presentation.sh still documents and performs an automatic local fallback when called directly. Since build.sh is now the declared single entry point and invokes the script from inside the container, this does not undermine the main workflow. It could be aligned later if direct script usage should follow the same explicit-local rule.
From my side this is mergeable. ✅
Make direct use of scripts/render-presentation.sh follow the same execution-mode contract as build.sh: container is the reproducible default, DOCS_TOOLBOX_LOCAL=1 opts into host rendering, and without a container engine (and without that flag) it aborts instead of silently rendering locally. Updates the usage text accordingly. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Apply PR #55 review feedback: - Reproducibility: pin the default image to docs-toolbox:v1.3.1 in both build.sh and scripts/render-presentation.sh instead of :latest, so the same commit always runs against the same toolchain. Override with DOCS_TOOLBOX_IMAGE (e.g. a digest) when needed. - File ownership: run the container with user mapping so generated files are not root-owned on native Linux — `--user $(id -u):$(id -g)` plus a writable HOME on Docker, `--userns=keep-id` on rootless Podman. Applies to build.sh and render-presentation.sh. - Explicit execution modes: container mode is the reproducible default; DOCS_TOOLBOX_LOCAL=1 opts into the host toolchain. Without a container engine and without that flag, tasks now abort instead of silently running locally. - Remove the redundant validate pass from `all` (build already validates via generate); `all` now runs test, check-adapters, and build. - Document the modes, pinning, ownership mapping, and abort behaviour in the README and the arc42 local-and-ci deployment doc. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
1 participant
Summary
Makes
build.shthe single entry point for every repository task and runs each task inside thedocs-as-code-toolkit/docs-toolboxcontainer image by default, with a documented local fallback. Local runs and CI now share one reproducible toolchain.Why
Previously tasks were split across raw
ruby/nodeinvocations and a render-onlybuild.sh, and CI installed Ruby and Node separately. The docs-toolbox image already had Ruby + Asciidoctor but lacked Node.js, so JS-based generators/tests could not run in it.Changes
v1.3.1+latest): addnodejs/npmso validators, generators, Ruby tests, JS tests, and doc builds all run in one image.build.sh: dispatcher with tasksvalidate,generate,test,test-ruby,test-js,adapters,check-adapters,build,presentation,all,clean,help. Each task container-wraps into docs-toolbox (auto-detects Docker/Podman) and falls back to local execution otherwise. Default image →docs-toolbox:v1.3.1; override viaDOCS_TOOLBOX_IMAGE.validate.yml,publish-docs.yml): dropsetup-ruby/setup-node; run./build.sh <task>so CI uses the same image as local../build.shfirst with the local command as fallback;architecture-core,honey-for-devs, the arc42local-and-cideployment doc, and thebdd-specificationverification note updated.Verification (via locally built v1.3.1 image)
./build.sh validate./build.sh test./build.sh check-adapters./build.sh generate./build.sh buildbuild/architecture/index.htmlrenderedOut of scope
example/bootstrap sample keeps its raw commands (nobuild.sh) — noted as a follow-up.🤖 Generated with Claude Code