diff --git a/README.md b/README.md index b1b5934..71a6b1f 100644 --- a/README.md +++ b/README.md @@ -159,7 +159,8 @@ share, and evolve prompts across projects. The repository is a collection of Markdown files organized in the `prompts/` subdirectory. Each file contains one or more related prompts or policy documents. There is no build step or runtime component; the prompts are consumed -by copying them into other projects or referencing them directly. +by copying them into other projects or referencing them directly. `examples/` +holds the example `Dockerfile` files that `prompts/REPO_POLICIES.md` links to. ## See Also diff --git a/examples/go-lint-system-libraries.Dockerfile b/examples/go-lint-system-libraries.Dockerfile new file mode 100644 index 0000000..ebe5198 --- /dev/null +++ b/examples/go-lint-system-libraries.Dockerfile @@ -0,0 +1,7 @@ +FROM golangci/golangci-lint@sha256:... AS lint +RUN apt-get update \ + && apt-get install -y --no-install-recommends libvips-dev \ + && rm -rf /var/lib/apt/lists/* +WORKDIR /src +COPY go.mod go.sum ./ +RUN go mod download diff --git a/examples/go.Dockerfile b/examples/go.Dockerfile new file mode 100644 index 0000000..a37862b --- /dev/null +++ b/examples/go.Dockerfile @@ -0,0 +1,77 @@ +# The steps that install system packages and download Go's modules +# come before COPY . ., so a change to the code keeps their layers. +# The steps that compile mount Go's build cache, and golangci-lint run +# also mounts golangci-lint's; both survive from build to build. + +# Lint phase +# golangci/golangci-lint:v2.x.x, YYYY-MM-DD +FROM golangci/golangci-lint@sha256:... AS lint +WORKDIR /src +COPY go.mod go.sum ./ +RUN go mod download +COPY . . +RUN --mount=type=cache,target=/root/.cache/go-build \ + --mount=type=cache,target=/root/.cache/golangci-lint \ + golangci-lint run --config .golangci.yml ./... + +# Test phase. -race needs cgo and so a C compiler, which the Debian Go +# image ships and the alpine one does not. -count=1 because the mounted +# cache also holds test results, which go test would otherwise replay. +# A first run that timed out gets no rerun, because a rerun would only +# wait for the same hang. +# golang:1.x, YYYY-MM-DD +FROM golang@sha256:... AS test +WORKDIR /src +COPY go.mod go.sum ./ +RUN go mod download +COPY . . +RUN --mount=type=cache,target=/root/.cache/go-build \ + status=0; \ + output=$(go test -count=1 -timeout 90s -race -cover ./... 2>&1) || status=$?; \ + printf '%s\n' "$output"; \ + test "$status" -eq 0 && exit 0; \ + case "$output" in \ + *"panic: test timed out"*|*"*** Test killed"*) exit 1 ;; \ + esac; \ + echo "--- Rerunning with -v for details ---"; \ + go test -count=1 -timeout 90s -race -v ./...; \ + exit 1 + +# Build stage. Nothing is wanted from either phase above; the copies +# are what make BuildKit build them first, so nothing after them can +# run unless lint and test passed. +# golang:1.x-alpine, YYYY-MM-DD +FROM golang@sha256:... AS builder +# git comes from the base image's own distribution package index, which +# is trusted, so it needs no version and no hash. +RUN apk add --no-cache git +WORKDIR /src +COPY go.mod go.sum ./ +RUN go mod download +COPY --from=lint /src/go.sum /dev/null +COPY --from=test /src/go.sum /dev/null +# A tar-stream context keeps the sender's file owners, which git refuses. +RUN git config --system --add safe.directory /src +COPY . . + +# The VERSION build arg when one is given, otherwise +# `git describe --tags --always` on the .git in the build context. With +# .git present, a version that is still empty, dev or unknown fails the +# build: git is missing or could not read the checkout. +ARG VERSION +RUN --mount=type=cache,target=/root/.cache/go-build \ + VERSION="${VERSION:-$(git describe --tags --always)}"; \ + if [ -e .git ]; then \ + case "$VERSION" in ""|dev|unknown) \ + echo "version is '$VERSION' although .git is present" >&2; \ + exit 1 ;; \ + esac; \ + fi; \ + CGO_ENABLED=0 go build -trimpath \ + -ldflags="-s -w -X main.Version=${VERSION}" \ + -o /app ./cmd/app/ + +# Runtime stage, and the last one +FROM alpine@sha256:... +COPY --from=builder /app /usr/local/bin/app +ENTRYPOINT ["app"] diff --git a/examples/python-test-phase.Dockerfile b/examples/python-test-phase.Dockerfile new file mode 100644 index 0000000..0950e31 --- /dev/null +++ b/examples/python-test-phase.Dockerfile @@ -0,0 +1,23 @@ +# Test phase. Both pytest runs share one 90-second timeout, so a hang +# uses it once and gets no rerun. +# debian:trixie-slim, YYYY-MM-DD +FROM debian@sha256:... AS test +# Python, pip and venv come from the distribution, which is trusted, so +# they need no version and no hash. make and git are base tools that +# script/bootstrap installs when they are missing. Installed here, they +# stay in their own layer when script/ changes. +RUN apt-get update \ + && apt-get install -y --no-install-recommends ca-certificates make git \ + python3 python3-venv \ + && rm -rf /var/lib/apt/lists/* +# script/bootstrap installs pipenv in a virtual environment at +# $HOME/.pipenv, and the tests below run that pipenv. +ENV PATH=/root/.pipenv/bin:$PATH +WORKDIR /app +COPY script/ script/ +COPY Pipfile Pipfile.lock ./ +RUN script/bootstrap +COPY . . +RUN timeout 90 sh -c 'pipenv run pytest || { \ + echo "--- Rerunning with -v for details ---"; \ + pipenv run pytest -v; exit 1; }' diff --git a/prompts/EXISTING_REPO_CHECKLIST.md b/prompts/EXISTING_REPO_CHECKLIST.md index feb8a5a..f609e7b 100644 --- a/prompts/EXISTING_REPO_CHECKLIST.md +++ b/prompts/EXISTING_REPO_CHECKLIST.md @@ -59,8 +59,8 @@ with your task. also mounts golangci-lint's (`--mount=type=cache,target=/root/.cache/golangci-lint`), and no step mounts anything else; both `go test` runs carry `-count=1`; a first run - that timed out gets no rerun, as in the canonical Go `Dockerfile` in - `REPO_POLICIES.md` + that timed out gets no rerun, as in `examples/go.Dockerfile` in the + `prompts` repo - [ ] Python: a `test` phase that installs its packages from `Pipfile.lock` does it before `COPY . .`, with `COPY script/ script/`, `COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When @@ -79,8 +79,8 @@ with your task. a package with no wheel for the image stops the install. In that step it installs no Python, because a step above it already did. `Pipfile` names no `python_version`, because `--deploy` stops when the distribution's Python - differs from it. The tests run after `COPY . .`, as in the Python `test` - phase example in `REPO_POLICIES.md` + differs from it. The tests run after `COPY . .`, as in + `examples/python-test-phase.Dockerfile` in the `prompts` repo - [ ] The gate phases invoke their tools directly, never through `make lint` or `script/test` — those are themselves a `docker build` and would recurse diff --git a/prompts/NEW_REPO_CHECKLIST.md b/prompts/NEW_REPO_CHECKLIST.md index 2eb3d48..b7a6a25 100644 --- a/prompts/NEW_REPO_CHECKLIST.md +++ b/prompts/NEW_REPO_CHECKLIST.md @@ -125,8 +125,8 @@ Template files can be fetched from: also mounts golangci-lint's (`--mount=type=cache,target=/root/.cache/golangci-lint`), and no step mounts anything else; both `go test` runs carry `-count=1`; a first run - that timed out gets no rerun, as in the canonical Go `Dockerfile` in - `REPO_POLICIES.md` + that timed out gets no rerun, as in `examples/go.Dockerfile` in the + `prompts` repo - Python: a `test` phase that installs its packages from `Pipfile.lock` does it before `COPY . .`, with `COPY script/ script/`, `COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When @@ -146,8 +146,8 @@ Template files can be fetched from: for the image stops the install. In that step it installs no Python, because a step above it already did. `Pipfile` names no `python_version`, because `--deploy` stops when the distribution's - Python differs from it. The tests run after `COPY . .`, as in the Python - `test` phase example in `REPO_POLICIES.md` + Python differs from it. The tests run after `COPY . .`, as in + `examples/python-test-phase.Dockerfile` in the `prompts` repo - Server: the final stage builds and runs the application - Non-server: the final stage brings up the dev environment diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index b5e93cf..35fbcdb 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -174,7 +174,8 @@ style conventions are in separate documents: With only `package.json` and `yarn.lock`, the install fails. Alpine's yarn 1 then says to enable corepack; never do that, and copy the missing files - instead. The Python and Go stages below need no yarn and copy no + instead. The stages in the `prompts` repo's `examples/go.Dockerfile` and + `examples/python-test-phase.Dockerfile` need no yarn and copy no `yarn.lock`, so `script/bootstrap` installs no node and no yarn there. `script/cibuild` runs the CI build, and the Gitea workflow calls it. The @@ -237,7 +238,7 @@ style conventions are in separate documents: up a development environment; for server repos it is the runtime image. The gate phases and the build stage start from their pinned base images and install what those images lack in either of these ways: - - inline, as the canonical Go `Dockerfile` below does for `git` + - inline, as the `prompts` repo's `examples/go.Dockerfile` does for `git` - by running `script/bootstrap`, as the `prompts` repo's own `Dockerfile` does for its yarn packages @@ -318,87 +319,8 @@ style conventions are in separate documents: The lint phase is based on the `golangci/golangci-lint` image (pinned by hash), so lint failures surface in seconds rather than after a full compile. The test phase is based on the Debian Go image. The canonical Go repo - `Dockerfile`: - - ```dockerfile - # The steps that install system packages and download Go's modules - # come before COPY . ., so a change to the code keeps their layers. - # The steps that compile mount Go's build cache, and golangci-lint run - # also mounts golangci-lint's; both survive from build to build. - - # Lint phase - # golangci/golangci-lint:v2.x.x, YYYY-MM-DD - FROM golangci/golangci-lint@sha256:... AS lint - WORKDIR /src - COPY go.mod go.sum ./ - RUN go mod download - COPY . . - RUN --mount=type=cache,target=/root/.cache/go-build \ - --mount=type=cache,target=/root/.cache/golangci-lint \ - golangci-lint run --config .golangci.yml ./... - - # Test phase. -race needs cgo and so a C compiler, which the Debian Go - # image ships and the alpine one does not. -count=1 because the mounted - # cache also holds test results, which go test would otherwise replay. - # A first run that timed out gets no rerun, because a rerun would only - # wait for the same hang. - # golang:1.x, YYYY-MM-DD - FROM golang@sha256:... AS test - WORKDIR /src - COPY go.mod go.sum ./ - RUN go mod download - COPY . . - RUN --mount=type=cache,target=/root/.cache/go-build \ - status=0; \ - output=$(go test -count=1 -timeout 90s -race -cover ./... 2>&1) || status=$?; \ - printf '%s\n' "$output"; \ - test "$status" -eq 0 && exit 0; \ - case "$output" in \ - *"panic: test timed out"*|*"*** Test killed"*) exit 1 ;; \ - esac; \ - echo "--- Rerunning with -v for details ---"; \ - go test -count=1 -timeout 90s -race -v ./...; \ - exit 1 - - # Build stage. Nothing is wanted from either phase above; the copies - # are what make BuildKit build them first, so nothing after them can - # run unless lint and test passed. - # golang:1.x-alpine, YYYY-MM-DD - FROM golang@sha256:... AS builder - # git comes from the base image's own distribution package index, which - # is trusted, so it needs no version and no hash. - RUN apk add --no-cache git - WORKDIR /src - COPY go.mod go.sum ./ - RUN go mod download - COPY --from=lint /src/go.sum /dev/null - COPY --from=test /src/go.sum /dev/null - # A tar-stream context keeps the sender's file owners, which git refuses. - RUN git config --system --add safe.directory /src - COPY . . - - # The VERSION build arg when one is given, otherwise - # `git describe --tags --always` on the .git in the build context. With - # .git present, a version that is still empty, dev or unknown fails the - # build: git is missing or could not read the checkout. - ARG VERSION - RUN --mount=type=cache,target=/root/.cache/go-build \ - VERSION="${VERSION:-$(git describe --tags --always)}"; \ - if [ -e .git ]; then \ - case "$VERSION" in ""|dev|unknown) \ - echo "version is '$VERSION' although .git is present" >&2; \ - exit 1 ;; \ - esac; \ - fi; \ - CGO_ENABLED=0 go build -trimpath \ - -ldflags="-s -w -X main.Version=${VERSION}" \ - -o /app ./cmd/app/ - - # Runtime stage, and the last one - FROM alpine@sha256:... - COPY --from=builder /app /usr/local/bin/app - ENTRYPOINT ["app"] - ``` + `Dockerfile` is at + `https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go.Dockerfile`. Key points: - The lint phase uses the `golangci/golangci-lint` image directly, so @@ -447,18 +369,9 @@ style conventions are in separate documents: lists in the same `RUN`, so the layer does not keep them. The test phase, on the Debian Go image, installs the libraries its tests need the same way. Either install goes right after `FROM`, so Docker keeps it until the - base image or the install line changes: - - ```dockerfile - FROM golangci/golangci-lint@sha256:... AS lint - RUN apt-get update \ - && apt-get install -y --no-install-recommends libvips-dev \ - && rm -rf /var/lib/apt/lists/* - WORKDIR /src - COPY go.mod go.sum ./ - RUN go mod download - ``` - + base image or the install line changes. The first lines of a lint phase + that installs system libraries are at + `https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/go-lint-system-libraries.Dockerfile`. - `.dockerignore` lets `.git` into the build context. It keeps out every git `config` at any depth (`**/.git/config`, `**/.git/modules/**/config`): - the repository's own @@ -575,35 +488,11 @@ style conventions are in separate documents: `$HOME/.pipenv/bin/pipenv lock`, after the `pip install` line has installed pipenv. - In the example below, `script/bootstrap` finds `make`, `git`, python and - venv already installed. The example copies no `yarn.lock`, so - `script/bootstrap` installs no node and no yarn. - - ```dockerfile - # Test phase. Both pytest runs share one 90-second timeout, so a hang - # uses it once and gets no rerun. - # debian:trixie-slim, YYYY-MM-DD - FROM debian@sha256:... AS test - # Python, pip and venv come from the distribution, which is trusted, so - # they need no version and no hash. make and git are base tools that - # script/bootstrap installs when they are missing. Installed here, they - # stay in their own layer when script/ changes. - RUN apt-get update \ - && apt-get install -y --no-install-recommends ca-certificates make git \ - python3 python3-venv \ - && rm -rf /var/lib/apt/lists/* - # script/bootstrap installs pipenv in a virtual environment at - # $HOME/.pipenv, and the tests below run that pipenv. - ENV PATH=/root/.pipenv/bin:$PATH - WORKDIR /app - COPY script/ script/ - COPY Pipfile Pipfile.lock ./ - RUN script/bootstrap - COPY . . - RUN timeout 90 sh -c 'pipenv run pytest || { \ - echo "--- Rerunning with -v for details ---"; \ - pipenv run pytest -v; exit 1; }' - ``` + In `examples/python-test-phase.Dockerfile`, `script/bootstrap` finds `make`, + `git`, python and venv already installed. The example copies no `yarn.lock`, + so `script/bootstrap` installs no node and no yarn. The Python `test` phase + example is at + `https://git.eeqj.de/sneak/prompts/raw/branch/main/examples/python-test-phase.Dockerfile`. - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that runs `script/cibuild` on push. The workflow's only other step checks out the @@ -749,11 +638,12 @@ style conventions are in separate documents: pipenv run pytest -v; exit 1; }' ``` - Both pytest runs share that one 90-second timeout, as in the `Dockerfile` - example above, so a hang uses it once and gets no rerun. Ctrl-C does not - stop a running `make test`, which goes on until the tests end or the 90 - seconds run out. On a Mac without `timeout`, the target fails until it is - installed. On a host, the target needs `$HOME/.pipenv/bin` on `PATH`. + Both pytest runs share that one 90-second timeout, as in the `prompts` + repo's `examples/python-test-phase.Dockerfile`, so a hang uses it once and + gets no rerun. Ctrl-C does not stop a running `make test`, which goes on + until the tests end or the 90 seconds run out. On a Mac without `timeout`, + the target fails until it is installed. On a host, the target needs + `$HOME/.pipenv/bin` on `PATH`. The `exit 1` ensures the target always fails after a rerun. The first run already proved the tests are broken, so the build must not pass even if a @@ -828,11 +718,11 @@ style conventions are in separate documents: - **A plain `docker build .` of a clone stamps the version that `git describe --tags --always` gives.** The version is derived from the `.git` - in the build context, as the canonical `Dockerfile` above shows. Without its - failure check, a missing `git` or an unreadable checkout would leave - `-X main.Version=` empty, and the build would still exit 0. `script/docker` - and `script/cibuild` pass the version they compute on the host; it takes - precedence. They do this byte-identically across repos: + in the build context, as the `prompts` repo's `examples/go.Dockerfile` shows. + Without its failure check, a missing `git` or an unreadable checkout would + leave `-X main.Version=` empty, and the build would still exit 0. + `script/docker` and `script/cibuild` pass the version they compute on the + host; it takes precedence. They do this byte-identically across repos: ```sh # The version and the tag each get their own line: a failing command