check / check (push) Successful in 2m3s
script/write-upstream-policy-files fetches the shared policy files from prompts over HTTP and writes them into a repo clone, or into its own repo. It commits nothing. A repo gets only the documents its own work uses; its copies of the others are deleted. It keeps a repo's own entries in .gitignore, .dockerignore, .editorconfig and .golangci.yml, and stops, writing nothing, rather than lose a line it cannot keep. script/commit-upstream-policy-files replaces script/update-policy. It fetches the current script/write-upstream-policy-files, runs it on its own repo and commits the result without pushing. make commit-upstream-policy-files replaces make update-policy. test/commit-upstream-policy-files.sh replaces test/update-policy.sh. The Dockerfile's test stage runs it with no timeout, with coreutils so that cp is GNU cp. Model: opus-5-5
297 lines
16 KiB
Markdown
297 lines
16 KiB
Markdown
---
|
|
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/<path>`
|
|
|
|
# 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/<name>`, `.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 <version>`. It writes
|
|
`.yarn/releases/yarn-<version>.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/<name>`
|
|
|
|
- [ ] 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/write-upstream-policy-files` — fetches the vendored policy files
|
|
from the `prompts` repo over HTTP and writes them into the repo; identical
|
|
across repos
|
|
- [ ] `script/commit-upstream-policy-files` /
|
|
`make commit-upstream-policy-files` — fetches the current
|
|
`script/write-upstream-policy-files`, runs it on the repo and commits the
|
|
result without pushing; 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`
|