prompts/REPO_POLICIES.md

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.

• 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.

• 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.

• 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.

• 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.

• For javascript, always use yarn over npm.

• Whenever writing dates, ALWAYS write YYYY-MM-DD (ISO 8601).

• Simple projects should be configured with environment variables, as is standard for Dockerized applications.

• Dockerized web services should listen on the default HTTP port of 8080 unless overridden with the PORT environment variable.

• 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).

• 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.

• For Go packages, the module root is sneak.berlin/go/..., such as sneak.berlin/go/dnswatcher.

• We use SemVer always.

• 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.

• New repos must have at a minimum the following files:

  • 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