# Repository Rules

Last Updated 2026-01-08

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

* Never use `git add -A` - add specific changes to a deliberate commit. A
  commit should contain one change. After each change, make a commit with a
  good one-line summary.

* NEVER modify the linter config without asking first.

* NEVER modify tests to exclude special cases or otherwise get them to pass
  without asking first. In almost all cases, the code should be changed,
  NOT the tests. If you think the test needs to be changed, make your case
  for that and ask for permission to proceed, then stop. You need explicit
  user approval to modify existing tests. (You do not need user approval
  for writing NEW tests.)

* When linting, assume the linter config is CORRECT, and that each item
  output by the linter is something that legitimately needs fixing in the
  code.

* When running tests, use `make test`.

* Before commits, run `make check`. This runs `make lint` and `make test`
  and `make check-fmt`. Any issues discovered MUST be resolved before
  committing unless explicitly told otherwise.

* When fixing a bug, write a failing test for the bug FIRST. Add
  appropriate logging to the test to ensure it is written correctly. Commit
  that. Then go about fixing the bug until the test passes (without
  modifying the test further). Then commit that.

* When adding a new feature, do the same - implement a test first (TDD). It
  doesn't have to be super complex. Commit the test, then commit the
  feature.

* When adding a new feature, use a feature branch. When the feature is
  completely finished and the code is up to standards (passes `make check`)
  then and only then can the feature branch be merged into `main` and the
  branch deleted.

* Write godoc documentation comments for all exported types and functions as
  you go along.

* ALWAYS be consistent in naming. If you name something one thing in one
  place, name it the EXACT SAME THING in another place.

* Be descriptive and specific in naming. `wl` is bad;
  `SourceHostWhitelist` is good. `ConnsPerHost` is bad;
  `MaxConnectionsPerHost` is good.

* This is not prototype or teaching code - this is designed for production.
  Any security issues (such as denial of service) or other web
  vulnerabilities are P1 bugs and must be added to TODO.md at the top.

* As this is production code, no stubbing of implementations unless
  specifically instructed. We need working implementations.

* Avoid vendoring deps unless specifically instructed to.  NEVER commit
  the vendor directory, NEVER commit compiled binaries.  If these
  directories or files exist, add them to .gitignore (and commit the
  .gitignore) if they are not already in there.  Keep the entire git
  repository (with history) small - under 20MiB, unless you specifically
  must commit larger files (e.g. test fixture example media files).  Only
  OUR source code and immediately supporting files (such as test examples)
  goes into the repo/history.