# Repository Rules

Last Updated 2026-10-27

These rules MUST be followed at all times. This is very important.

- Never use `git add -A`. Stage specific changes for a deliberate commit. A
  commit holds one change. After each change, make a commit with a good one-line
  summary.

- NEVER modify the linter config without asking first.

- NEVER modify a test to exclude special cases or otherwise make it pass without
  asking first. In almost all cases, change the code, NOT the test. You need
  explicit user approval to modify an existing test. If you think a test needs
  to change, make your case and ask for permission to proceed. Then stop. A bug
  fix may change an existing test without asking only when that test pins
  exactly the behavior the filed bug calls wrong. The change must then move the
  test to the fixed behavior and nothing else. Any other change to an existing
  test needs explicit user approval. Writing NEW tests needs no approval.

- When linting, assume the linter config is CORRECT. Treat each item the linter
  reports as something that legitimately needs fixing in the code.

- When running tests, use `make test`.

- Before committing, run `make check`. It runs `make test`, `make lint` and
  `make fmt-check`. Any issue it finds MUST be resolved before committing,
  unless you are explicitly told otherwise.

- When fixing a bug, write a failing test for the bug FIRST. Add appropriate
  logging to the test, to make sure the test is written correctly. Commit that.
  Then fix the bug until the test passes, without modifying the test further.
  Then commit the fix.

- When adding a new feature, do the same: write a test first (test-driven
  development, TDD). The test does not need to be very complex. Commit the test,
  then commit the feature.

- When adding a new feature, use a feature branch. A feature branch lands on
  `next` through a reviewed PR. The branch is merged, and then deleted, only
  when the feature is completely finished and the code passes `make check`. Only
  the owner merges `next` into `main`.

- Write `godoc` comments for all exported types and functions as you go along.

- ALWAYS be consistent in naming. If you name something one way in one place,
  use the EXACT SAME name in every other place.

- Be descriptive and specific in naming. `wl` is bad; `SourceHostAllowlist` is
  good. `ConnsPerHost` is bad; `MaxConnectionsPerHost` is good.

- This is not prototype or teaching code. It is designed for production. Any
  security issue (such as denial of service) or other web vulnerability is a P1
  bug, the highest priority. It must be added at the top of `TODO.md`.

- Do not stub an implementation unless you are specifically instructed to. This
  is production code, and we need working implementations.

- NEVER silently fall back to a different setting when a user's parameter
  explicitly specifies a value. Return an error instead. For example, if a user
  requests `format=webp` and WebP encoding is not supported, return an error. Do
  NOT silently output PNG instead. If a user specifies `fit=invalid` and that
  fit mode does not exist, return an error. Do NOT silently default to `cover`.
  A silent fallback violates the principle of least surprise and masks bugs.
  Defaults are acceptable only for OMITTED parameters, never for INVALID
  explicit values.

- Avoid vendoring dependencies unless specifically instructed to. NEVER commit
  the `vendor/` directory. NEVER commit compiled binaries. If such a directory
  or file exists and `.gitignore` does not list it, add it to `.gitignore`.
  Commit that `.gitignore` change. Keep the entire git repository, history
  included, under 20 MiB. Commit a larger file only when you specifically must.
  Media files used as test fixtures are one such case. Only OUR source code and
  its immediately supporting files, such as test examples, go into the
  repository and its history.