diff --git a/docs/EXISTING_REPO_CHECKLIST.md b/docs/EXISTING_REPO_CHECKLIST.md new file mode 100644 index 0000000..812b43e --- /dev/null +++ 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 diff --git a/docs/NEW_REPO_CHECKLIST.md b/docs/NEW_REPO_CHECKLIST.md new file mode 100644 index 0000000..2f48220 --- /dev/null +++ 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/` + +## 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/`, `.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`