sneak/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Copyedit REPO_POLICIES.md for clarity and succinctness

Browse Source 
Tighten prose throughout while preserving all policy details.
Add note that make check must not modify repo files.
This commit is contained in:
Jeffrey Paul 2026-02-22 15:49:20 +01:00
parent ab7422c850
commit aaae9714da
1 changed files with 64 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

155
REPO_POLICIES.md
View File

@ -1,114 +1,87 @@
# Development Policies # Development Policies
- Docker image references by tag are server-mutable, therefore using them is - All references to Docker images, Go modules, and packages must use
an RCE vulnerability. All docker image references must use cryptographic cryptographic hashes. Mutable references (tags, `@latest`, etc.) are
hashes to securely specify the exact image that is expected. remote code execution vulnerabilities.
- Correspondingly, `go install` commands using things like '@latest' are - Every repo with software must have a root `Makefile` with these targets:
also dangerous RCE. Whenever writing scripts or tools, ALWAYS specify go `make test`, `make lint`, `make fmt` (writes), `make fmt-check`
install targets using commit hashes which are cryptographically secure. (read-only), `make check` (prereqs: `test`, `lint`, `fmt-check`), and
`make docker`.
- 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.
- Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.) - Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
instead of invoking the underlying tools directly. The Makefile is the instead of invoking the underlying tools directly. The Makefile is the
single source of truth for how these operations are run. 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 - Every repo should have a `Dockerfile`. For non-server repos, the
feature branch. 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 - Use platform-standard formatters: `black` for Python, `prettier` for
modified by an agent, only manually by the user. It can be copied from JS/CSS, `go fmt` for Go. Always use default configuration with one
`~/dev/upaas/.golangci.yml` if it exists at that location. exception: set four-space indents for everything except Go.
- When specifying images or packages by hash in Dockerfiles or - Pre-commit hook: `make check` if local testing is possible, otherwise
`docker-compose.yml`, put a comment above the line and show the version `make lint && make fmt-check`.
and date at which it was current.
- 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 - `make check` must not modify any files in the repo. Tests may use
standard for Dockerized applications. temporary directories.
- Dockerized web services should listen on the default HTTP port of 8080 - `main` must always pass `make check`, no exceptions.
unless overridden with the `PORT` environment variable.
- The `README.md` is a project's primary documentation. It should contain - Make all changes on a feature branch. You can do whatever you want on
at a minimum the following sections: a feature branch.
- 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`).
- When beginning a new project, initialize a git repo and make the first - `.golangci.yml` is standardized and must _NEVER_ be modified by an
commit simply the first version of the README.md in the root of the repo. 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 - When pinning images or packages by hash, add a comment above the
as `sneak.berlin/go/dnswatcher`. 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 - Write all dates as YYYY-MM-DD (ISO 8601).
migrations and assume no installed base or existing databases. If
`>=1.0.0`, database changes add new migration files.
- 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/<name>`.
- 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` - `README.md`, `.git`, `.gitignore`
- `REPO_POLICIES.md` (copy from the `prompts` repo) - `REPO_POLICIES.md` (copy from the `prompts` repo)
- `Dockerfile`, `.dockerignore` - `Dockerfile`, `.dockerignore`
- for go: `go.mod`, `go.sum`, `.golangci.yml` - Go: `go.mod`, `go.sum`, `.golangci.yml`
- for js: `package.json` - JS: `package.json`