diff --git a/REPO_POLICIES.md b/REPO_POLICIES.md index eae9789..7ce111c 100644 --- a/REPO_POLICIES.md +++ b/REPO_POLICIES.md @@ -1,114 +1,87 @@ # Development Policies -- Docker image references by tag are server-mutable, therefore using them is - an RCE vulnerability. All docker image references must use cryptographic - hashes to securely specify the exact image that is expected. +- All references to Docker images, Go modules, and packages must use + cryptographic hashes. Mutable references (tags, `@latest`, etc.) are + remote code execution vulnerabilities. -- Correspondingly, `go install` commands using things like '@latest' are - also dangerous RCE. Whenever writing scripts or tools, ALWAYS specify go - install targets using commit hashes which are cryptographically secure. - -- Every repo with software in it must have a Makefile in the root. Each - such Makefile should support `make test` (runs the project-specific - tests), `make lint`, `make fmt` (writes), `make fmt-check` (readonly), and - `make check` (has `test`, `lint`, and `fmt-check` as prereqs), `make -docker` (builds docker image). - -- Every repo should have a Dockerfile. If the repo contains non-server - software, the Dockerfile should bring up a development environment and - `make check` (i.e. the docker build should fail if the branch is not - green). - -- Platform-specific standard formatting should be used. `black` for python, - `prettier` for js/css/etc, `go fmt` for go. The only changes to default - settings should be to specify four-space indents where applicable (i.e. - everything except `go fmt`). - -- If local testing is possible (it is not always), `make check` should be a - pre-commit hook. If it is not possible, `make lint && make fmt-check` - should be a pre-commit hook. - -- If a working `make test` takes more than 20 seconds, that's a bug that - needs fixing. In fact, there should be a timeout specified in the - `Makefile` that fails it automatically if it takes >30s. - -- Docker builds should time out in 5 minutes or less. - -- `main` must always pass `make check`, no exceptions. +- Every repo with software must have a root `Makefile` with these targets: + `make test`, `make lint`, `make fmt` (writes), `make fmt-check` + (read-only), `make check` (prereqs: `test`, `lint`, `fmt-check`), and + `make docker`. - Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.) instead of invoking the underlying tools directly. The Makefile is the single source of truth for how these operations are run. -- Do all changes on a feature branch. You can do whatever you want on a - feature branch. +- Every repo should have a `Dockerfile`. For non-server repos, the + Dockerfile should bring up a development environment and run + `make check` (the build should fail if the branch is not green). -- We have a standardized `.golangci.yml` which we reuse and is _NEVER_ to be - modified by an agent, only manually by the user. It can be copied from - `~/dev/upaas/.golangci.yml` if it exists at that location. +- Use platform-standard formatters: `black` for Python, `prettier` for + JS/CSS, `go fmt` for Go. Always use default configuration with one + exception: set four-space indents for everything except Go. -- When specifying images or packages by hash in Dockerfiles or - `docker-compose.yml`, put a comment above the line and show the version - and date at which it was current. +- Pre-commit hook: `make check` if local testing is possible, otherwise + `make lint && make fmt-check`. -- For javascript, always use `yarn` over `npm`. +- `make test` must complete in under 20 seconds. Add a 30-second timeout + in the Makefile. -- Whenever writing dates, ALWAYS write YYYY-MM-DD (ISO 8601). +- Docker builds must complete in under 5 minutes. -- Simple projects should be configured with environment variables, as is - standard for Dockerized applications. +- `make check` must not modify any files in the repo. Tests may use + temporary directories. -- Dockerized web services should listen on the default HTTP port of 8080 - unless overridden with the `PORT` environment variable. +- `main` must always pass `make check`, no exceptions. -- The `README.md` is a project's primary documentation. It should contain - at a minimum the following sections: - - Description - - Include a short and complete description of the functionality and - purpose of the software as the first line in the readme. It must - include: - - the name - - the purpose - - the category (web server, SPA, command line tool, etc) - - the license - - the author - - eg: "µPaaS is an MIT-licensed Go web application by @sneak - that receives git-frontend webhooks and interacts with a - Docker server to build and deploy applications in realtime as - certain branches are updated." - - Getting Started - - a code block with copy-pasteable installation/use sections - - Rationale - - why does this exist? - - Design - - how is the program structured? - - TODO - - This is your TODO list for the project - update it meticulously, - even in between commits. Whenever planning, put your todo list in - the README so that a separate agent with new context can pick up - where you left off. - - License - - GPL or MIT or WTFPL - ask the user when beginning a new project - and include a LICENSE file in the root and in a section in the - README. - - Author - - @sneak (link `@sneak` to `https://sneak.berlin`). +- Make all changes on a feature branch. You can do whatever you want on + a feature branch. -- When beginning a new project, initialize a git repo and make the first - commit simply the first version of the README.md in the root of the repo. +- `.golangci.yml` is standardized and must _NEVER_ be modified by an + agent, only manually by the user. Copy from + `~/dev/upaas/.golangci.yml` if available. -- For Go packages, the module root is `sneak.berlin/go/...`, such - as `sneak.berlin/go/dnswatcher`. +- When pinning images or packages by hash, add a comment above the + reference with the version and date (YYYY-MM-DD). -- We use SemVer always. +- Use `yarn`, not `npm`. -- If no tag `1.0.0` or greater exists in the repository, modify the existing - migrations and assume no installed base or existing databases. If - `>=1.0.0`, database changes add new migration files. +- Write all dates as YYYY-MM-DD (ISO 8601). -- New repos must have at a minimum the following files: +- Simple projects should be configured with environment variables. + +- Dockerized web services listen on port 8080 by default, overridable + with `PORT`. + +- `README.md` is the primary documentation. Required sections: + - **Description**: First line must include the project name, purpose, + category (web server, SPA, CLI tool, etc.), license, and author. + Example: "µPaaS is an MIT-licensed Go web application by @sneak + that receives git-frontend webhooks and deploys applications via + Docker in realtime." + - **Getting Started**: Copy-pasteable install/usage code block. + - **Rationale**: Why does this exist? + - **Design**: How is the program structured? + - **TODO**: Update meticulously, even between commits. When + planning, put the todo list in the README so a new agent can pick + up where the last one left off. + - **License**: MIT, GPL, or WTFPL. Ask the user for new projects. + Include a `LICENSE` file in the repo root and a License section in + the README. + - **Author**: [@sneak](https://sneak.berlin). + +- First commit of a new repo should contain only `README.md`. + +- Go module root: `sneak.berlin/go/`. + +- Use SemVer. + +- Pre-1.0.0: modify existing migrations (no installed base assumed). + Post-1.0.0: add new migration files. + +- New repos must contain at minimum: - `README.md`, `.git`, `.gitignore` - `REPO_POLICIES.md` (copy from the `prompts` repo) - `Dockerfile`, `.dockerignore` - - for go: `go.mod`, `go.sum`, `.golangci.yml` - - for js: `package.json` + - Go: `go.mod`, `go.sum`, `.golangci.yml` + - JS: `package.json`