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
- 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/<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`
- `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`