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