--- title: New Repo Checklist last_modified: 2026-11-16 --- Use this checklist when creating a new repository from scratch. Follow the steps in order. Full policies are at `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`. Template files can be fetched from: `https://git.eeqj.de/sneak/prompts/raw/branch/main/` # 1. Initialize - [ ] `git init` - [ ] Ask the user for the license (MIT, GPL, or WTFPL) # 2. First Commit (README only) - [ ] Create `README.md` with all required sections: - [ ] **Description**: name, purpose, category, license, author - [ ] **Getting Started**: copy-pasteable code block - [ ] **Rationale**: why does this exist? - [ ] **Design**: how is it structured? - [ ] **TODO**: initial task list - [ ] **License**: matches chosen license - [ ] **Author**: [@sneak](https://sneak.berlin) - [ ] `git add README.md && git commit` # 3. Scaffolding (feature branch) - [ ] `git checkout -b initial-scaffolding` ## Fetch Template Files - [ ] `.gitignore` — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore`, then add the repo's own build outputs, such as its binaries, at the end of the file, where a re-vendor keeps them. Extensions are written to `.gitignore`'s own semantics, where an unanchored pattern already matches at every depth: never add a `**/` prefix here, which is a `.dockerignore` form. The canonical file already carries `.claude/` so agent worktrees cannot be committed by accident. - [ ] `.editorconfig` — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`, then add the repo's own sections, such as one for another language it uses, at the end of the file, where a re-vendor keeps them. - [ ] `Makefile` — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`, adapt targets for the project's language and tools - [ ] For JS/docs repos: `.prettierrc` and `.prettierignore` — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierrc` and `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierignore` ## Create Project Files - [ ] `LICENSE` file matching the chosen license - [ ] `REPO_POLICIES.md` — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md` - [ ] Guidance for coding agents, if the repo has any, is one `AGENTS.md` at the root — never a file or directory named after one agent tool, such as `CLAUDE.md` or `.claude/`, and never separate memory files - [ ] `Dockerfile` and `.dockerignore` — fetch `.dockerignore` from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` - The repo's own entries go at the end of the file, where a re-vendor keeps them. - Extend `.dockerignore` with the repo's own host-built artifacts, giving every depth-independent pattern a `**/` prefix — but write a repo-root binary anchored, `/myapp` and never `**/myapp`, which would also match `cmd/myapp/` and delete the package directory. Do not transplant `.gitignore`'s patterns: `.dockerignore` anchors an unprefixed pattern at the context root, so the copied form leaves `config/.env` in the build context while reading as solved. The canonical file's `.claude` entry is anchored for the same reason as a repo-root binary; leave it that way, but note that it only covers agents running at the repo root — if this repo will run them in subdirectories, `services/api/.claude/` needs its own anchored entry. - If the image embeds a version in a binary: `.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 - each submodule's under `.git/modules/` - that of a submodule keeping its own `.git` directory `git describe` does not need them, and each can hold a credential: a password in a remote URL, or the token the CI checkout step stores there. Some submodule names have a `config` segment, as in `config`, `deploy/config` or `config/lib`. Such a submodule loses its whole git directory to `**/.git/modules/**/config`, and Go's version stamping then fails the build. Give it a name without that segment (`git submodule add --name`). The stage that compiles has `git`: the Debian Go image has it, and an alpine one needs `apk add --no-cache git`. That stage takes the version from the `VERSION` build argument when one is given, otherwise from `git describe --tags --always`. That gives: - the tag, on a tagged commit - the tag, the number of commits since it and the short commit (`v1.2.3-4-gabc1234`), on a later commit - the short commit, when no tag is reachable The stage that compiles also marks its working directory safe for git (`git config --system --add safe.directory /src`). A context sent as a tar stream keeps the sender's file owners, and git refuses a checkout owned by another user, so the version would come out empty. `ARG VERSION` has no default. The build fails if the context carries `.git` and the version still comes out empty, `dev` or `unknown`. A plain `docker build .` with no build arguments must succeed; a Dockerfile that refuses an empty build argument drops that refusal and keeps the argument. A checkout whose `.git` is a file is the exception: a linked worktree, or a repository checked out as a submodule. That file points to a git directory outside the build context, so the build cannot read the version and a plain `docker build .` fails. Pass the version with `--build-arg VERSION=...`, as `script/docker` and `script/cibuild` already do. - The Dockerfile carries a `lint` phase and a `test` phase, each invoking its tool directly rather than through `make` or `script/`, and the final stage carries a `COPY --from=` of a harmless file from each so the image cannot be built unless both passed. Keep the final stage last: a stage nothing depends on is built only when `--target` names it. - Go: each Go stage downloads the modules (`COPY go.mod go.sum ./`, `RUN go mod download`) before `COPY . .`; the steps that compile (`golangci-lint run`, `go test`, `go build`) mount Go's build cache (`--mount=type=cache,target=/root/.cache/go-build`), `golangci-lint run` 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` - 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 `script/bootstrap` runs in that step, it installs nothing beyond these: - system packages - pipenv and its dependencies - the packages from `Pipfile.lock` It creates a virtual environment at `$HOME/.pipenv` with `python3 -m venv` when it is missing, then uses that environment's `pip` and `pipenv`. On a host, it first installs the distribution's python and venv packages when they are missing. It installs pipenv and its dependencies by hash, with `pip install --require-hashes`. It installs the packages from `Pipfile.lock` with `pipenv install --deploy`, plus `--dev` when the tests need the development packages. It sets `PIP_ONLY_BINARY=:all:` for both installs, so 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` - Server: the final stage builds and runs the application - Non-server: the final stage brings up the dev environment - Image pinned by sha256 hash with version/date comment - [ ] Gitea Actions workflow at `.gitea/workflows/check.yml` that runs `script/cibuild` on push, checks out with `persist-credentials: false` and with `fetch-depth: 0` (which fetches the tags `git describe` needs), carries the `concurrency` block that lets a new push cancel only the same branch's older run, and sets `timeout-minutes: 20` on the `check` job so a hung build frees the shared runner — reference `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml` - [ ] Language-specific: - [ ] Go: `go mod init sneak.berlin/go/`, `.golangci.yml` (fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and, in the same commit, set the lint phase digest to the one named in the `.golangci.yml` paragraph of `REPO_POLICIES.md`) - [ ] JS, or any repository that runs prettier through yarn: make the first `yarn.lock` with the steps below. `script/bootstrap` installs no yarn until `yarn.lock` exists, so run them with any distribution's node and yarn, such as Alpine's (`apk add nodejs-current yarn`). Use `yarnpkg` on Debian and Ubuntu. 1. Read the version from `yarnPath` in `https://git.eeqj.de/sneak/prompts/raw/branch/main/.yarnrc.yml`. 2. Run `yarn set version `. It writes `.yarn/releases/yarn-.cjs`, `.yarnrc.yml` and `package.json`. 3. Add `nodeLinker: node-modules` and `enableTelemetry: false` to `.yarnrc.yml`. 4. Add `"private": true` to `package.json`. 5. Run `yarn add --dev prettier`. It writes `yarn.lock`. 6. Add `.yarn/releases/** binary` to `.gitattributes`. 7. Run `yarn install --immutable`. It must pass and change nothing. - [ ] Python: `pyproject.toml` ## Configure script/ Entrypoints and Makefile Implementations live in `script/` (scripts-to-rule-them-all); Makefile targets are thin shims calling them. Model scripts: `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/` - [ ] scripts are POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run on alpine images without bash - [ ] `script/bootstrap` / `make bootstrap` installs all dependencies, idempotently, and assumes nothing is present: - It detects the package manager: nix, apt, brew or apk. - It installs node, yarn and the node packages only when `yarn.lock` is in the tree. node and yarn come from that package manager when they are missing. - It installs the node packages with `yarn install --immutable`. The distribution's yarn only starts the release file that `yarnPath` in `.yarnrc.yml` names, and that file does the work. - A non-server repo's development environment stage runs it, with only system packages installed inline above it. - A gate phase or the build stage installs what its base image lacks, either inline or by running it. - [ ] A `Dockerfile` stage that needs yarn may start from any distribution that packages node and yarn. It copies `package.json`, `yarn.lock`, `.yarnrc.yml` and `.yarn/releases/` before it runs `script/bootstrap`. A stage that needs no yarn copies none of them. - [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`, then `install-precommit`, plus repo-specific init - [ ] `script/test` / `make test` — `docker build --target test --output type=cacheonly .`, which writes no image; the phase runs real tests, not a no-op (90-second timeout, 60-second hard cap on wall time) - [ ] `script/lint` / `make lint` — `docker build --target lint --output type=cacheonly .`, which writes no image. No lint verdict may come from a host invocation of the linter. - [ ] `script/fmt` / `make fmt` — formats code (writes; native, never in a container). Go code gets `gofmt`, then `golines -m 77`. - [ ] `script/fmt-check` / `make fmt-check` — checks formatting (read-only; native). Fails when `gofmt` or `golines -m 77` would change a Go file. - [ ] Go: `script/bootstrap` installs `golines` with `go install` pinned to a commit hash - [ ] `script/check` / `make check` — runs `test`, `lint`, `fmt-check`; must not modify files - [ ] `script/projectname` — outputs the project name (used by `script/docker` for the image tag) - [ ] `script/docker` / `make docker` — builds Docker image, tagged via `script/projectname` (byte-identical across repos), with the version as a build arg - [ ] `script/cibuild` — cd to repo root, run `script/bootstrap`, run `script/check`, then `docker build --build-arg VERSION="$version" -t "$tag" .` (what CI runs), with `$version` from `git describe --tags --always --dirty` (`unknown` if empty) and `$tag` from `script/projectname`, each assigned on its own line before the build. The bootstrap is required: CI checks out and runs this alone, and `script/fmt-check` runs the formatter on the host. - [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu. With neither name on `PATH`, `script/fmt` and `script/fmt-check` print one line saying to run `script/bootstrap`, and exit 1. - [ ] No `docker build` in `script/` leaves a dangling image behind: `script/lint` and `script/test` write no image, and `script/docker` and `script/cibuild` tag theirs - [ ] `script/precommit` — called by the pre-commit hook; runs `script/check` - [ ] `script/install-precommit` — installs the pre-commit hook that runs `script/precommit` - [ ] `make hooks` — shims to `script/install-precommit` - [ ] `script/update-policy` / `make update-policy` — fetches the vendored policy files from the `prompts` repo, commits them and pushes; identical across repos - [ ] README **Entrypoints** section documents the scripts and links the standard # 4. Verify - [ ] `make check` passes - [ ] `make docker` succeeds - [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has. That host is the runner image `docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and node 24. Take any yarn off `PATH` first. - [ ] Plant a lint violation and confirm both `make lint` and a plain `docker build .` fail on it; revert. A plain build that passes proves the final stage is missing its `COPY --from=` edge to the gate phases. - [ ] No secrets in repo, and none in the build context: enumerate a probe image rather than reading `.dockerignore` - [ ] No mutable references to what the repo downloads and installs itself in scripts and Dockerfiles. Distribution packages are outside this rule. They need no version and no hash, and updating and upgrading them is fine too. In a `Dockerfile`, the distribution is the pinned base image's. On a host, it is the host's, and the host's package manager stands for it, nix and brew included. A package source that a `Dockerfile` adds itself is not the distribution's own, so its packages are pinned - [ ] node, yarn, npm, python, pip and venv come from the distribution wherever possible, never from nvm, pyenv, corepack or `npm install -g yarn`. If the distribution's version is too old, use a newer distribution. node means the distribution's newest Node package, such as `nodejs-current` on Alpine 3.24 - [ ] yarn's release file is in git under `.yarn/releases/`, written once by `yarn set version` with an exact version (repositories with `yarn.lock`) - [ ] No unnecessary files in repo root - [ ] All dates written as YYYY-MM-DD # 5. Merge and Set Up - [ ] Commit, merge to `main` - [ ] `make hooks` to install pre-commit hook - [ ] Add remote and push - [ ] Verify `main` passes `make check`