81 lines
3.6 KiB
Markdown
81 lines
3.6 KiB
Markdown
# Repository Rules
|
|
|
|
Last Updated 2026-01-10
|
|
|
|
These rules MUST be followed at all times, it is very important.
|
|
|
|
* Do NOT stop working while there are still incomplete TODOs in the todo list
|
|
or in TODO.md. Continue implementing until all tasks are complete or you are
|
|
explicitly told to stop.
|
|
|
|
* 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.
|
|
|
|
* 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.
|
|
|
|
* 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.
|