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.

• 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