diff --git a/AGENTS.md b/AGENTS.md index 3933bc0..0c9b650 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,75 +1,75 @@ # 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. The feature branch is merged + into `next`, and then deleted, only when the feature is completely finished + and the code is up to standards. The code is up to standards when it passes + `make check`. Only the user 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. `al` 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. 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. 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. Go over 20 MiB only when you specifically must commit + a large file, such as a media file used as a test fixture. Only OUR source + code and its immediately supporting files, such as test examples, go into the + repository and its history.