Add checklists for existing and new repo setup

2026-02-22 16:10:28 +01:00 · 2026-02-22 16:10:28 +01:00 · d1a98c2413
commit d1a98c2413
parent 06f279fa5b
2 changed files with 148 additions and 0 deletions
--- a/docs/EXISTING_REPO_CHECKLIST.md
+++ b/docs/EXISTING_REPO_CHECKLIST.md
@ -0,0 +1,69 @@
+# Existing Repo Checklist
+
+Use this checklist when beginning work in a repo that may not yet
+conform to our
+[development policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/REPO_POLICIES.md).
+
+Work on a feature branch. Check each item and fix any gaps before
+proceeding with your task.
+
+## Required Files
+
+- [ ] `README.md` exists with all required sections (Description,
+      Getting Started, Rationale, Design, TODO, License, Author)
+- [ ] `LICENSE` file exists and matches the README
+- [ ] `REPO_POLICIES.md` exists and version date is current with the
+      [authoritative source](https://git.eeqj.de/sneak/prompts/raw/branch/main/REPO_POLICIES.md)
+- [ ] `.gitignore` is comprehensive (OS, editor, language artifacts,
+      secrets) — fetch from
+      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore`
+      if missing
+- [ ] `.editorconfig` exists
+- [ ] `Dockerfile` and `.dockerignore` exist
+- [ ] Language-specific config:
+    - [ ] Go: `go.mod`, `go.sum`, `.golangci.yml`
+    - [ ] JS: `package.json`, `yarn.lock`, `.prettierrc`,
+          `.prettierignore`
+    - [ ] Python: `pyproject.toml`
+    - [ ] Docs/writing: `.prettierrc`, `.prettierignore`
+
+## Makefile
+
+- [ ] `Makefile` exists in root — reference the
+      [model Makefile](https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile)
+- [ ] Has targets: `test`, `lint`, `fmt`, `fmt-check`, `check`,
+      `docker`, `hooks`
+- [ ] `make check` does not modify any files in the repo
+- [ ] `make test` has a 30-second timeout
+- [ ] `make check` passes on current branch
+
+## Formatting
+
+- [ ] Platform-standard formatter is configured (`black`, `prettier`,
+      `go fmt`)
+- [ ] Default formatter config, only exception: four-space indents
+      (except Go)
+- [ ] All files pass `make fmt-check`
+
+## Git Hygiene
+
+- [ ] Pre-commit hook is installed (`make hooks`)
+- [ ] No secrets in the repo (`.env`, keys, credentials)
+- [ ] No mutable references in Dockerfiles or scripts (tags,
+      `@latest`) — all pinned by cryptographic hash with version/date
+      comment
+- [ ] Using `yarn`, not `npm` (JS projects)
+
+## Directory Structure
+
+- [ ] No unnecessary files in repo root
+- [ ] Files organized into canonical subdirectories (`bin/`, `cmd/`,
+      `docs/`, `internal/`, `static/`, etc.)
+- [ ] Go migrations in `internal/db/migrations/` and embedded in
+      binary
+
+## Final
+
+- [ ] `make check` passes
+- [ ] `docker build` succeeds
+- [ ] Commit and merge fixes before starting your actual task
--- a/docs/NEW_REPO_CHECKLIST.md
+++ b/docs/NEW_REPO_CHECKLIST.md
@ -0,0 +1,79 @@
+# New Repo Checklist
+
+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/REPO_POLICIES.md`
+
+Template files can be fetched from:
+`https://git.eeqj.de/sneak/prompts/raw/branch/main/<filename>`
+
+## 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 prompts repo, extend for
+      language-specific artifacts
+- [ ] `.editorconfig` — fetch from prompts repo
+- [ ] `Makefile` — fetch from prompts repo, adapt targets for the
+      project's language and tools
+- [ ] For JS/docs repos: `.prettierrc`, `.prettierignore`
+
+### Create Project Files
+
+- [ ] `LICENSE` file matching the chosen license
+- [ ] `REPO_POLICIES.md` — fetch from prompts repo
+- [ ] `Dockerfile` and `.dockerignore`
+    - Server: runs the application
+    - Non-server: brings up dev environment and runs `make check`
+    - Image pinned by sha256 hash with version/date comment
+- [ ] Language-specific:
+    - [ ] Go: `go mod init sneak.berlin/go/<name>`, `.golangci.yml`
+          (copy from `~/dev/upaas/.golangci.yml`)
+    - [ ] JS: `yarn init`, `yarn add --dev prettier`
+    - [ ] Python: `pyproject.toml`
+
+### Configure Makefile
+
+- [ ] `make test` — runs project tests (30-second timeout)
+- [ ] `make lint` — runs linter
+- [ ] `make fmt` — formats code (writes)
+- [ ] `make fmt-check` — checks formatting (read-only)
+- [ ] `make check` — prereqs: `test`, `lint`, `fmt-check`; must not
+      modify files
+- [ ] `make docker` — builds Docker image
+- [ ] `make hooks` — installs pre-commit hook
+
+## 4. Verify
+
+- [ ] `make check` passes
+- [ ] `make docker` succeeds
+- [ ] No secrets in repo
+- [ ] No mutable image/package references
+- [ ] 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`