diff --git a/AGENTS.md b/AGENTS.md index 3933bc0..23ff2cc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,75 +1,76 @@ # Repository Rules -Last Updated 2026-01-08 +Last Updated 2026-10-27 -These rules MUST be followed at all times, it is very important. +These rules MUST be followed at all times. This 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 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 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. A bug fix may change an existing test without asking - when that test pins exactly the behavior the filed bug calls wrong, and the - change moves it to the fixed behavior and nothing else; any other change to an - existing test still needs explicit user approval. (You do not need user - approval for writing NEW tests.) +- 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, and that each item output - by the linter is something that legitimately needs fixing in the code. +- 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 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. +- 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 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. + 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 - 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, 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. 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. +- 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 documentation comments for all exported types and functions as you - go along. +- Write `godoc` 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. +- 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; `SourceHostWhitelist` is +- 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 - 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. +- 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`. -- As this is production code, no stubbing of implementations unless specifically - instructed. We need working implementations. +- 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. 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 doesn't exist, return an error - - do NOT silently default to "cover". Silent fallbacks violate the principle of - least surprise and mask bugs. The only acceptable defaults are for OMITTED - parameters, never for INVALID explicit values. + 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 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. +- 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.