AGENTS.md

1 
2* Brevity is good.
3* Assume that the maintainers and readers of the code you write are Go experts:
4   * Don't use comments to explain the obvious.
5   * Use self-explanatory variable and function names.
6   * Use short variable names when the context is clear.
7* If you need to add temporary debug printing, use `hdebug.Printf`.[^1]
8* Never export symbols that's not needed outside of the package.
9* Avoid global state at (almost) all cost.
10* This is a project with a long history; assume that a similiar problem has been solved before, look hard for helper functions before creating new ones.
11* In tests, almost always write end-to-end integration tests using `hugolib.Test` or one of its siblings. Write unit tests only for isolated utilities.
12* In tests, use `qt` matchers (e.g. `b.Assert(err, qt.ErrorMatches, ...)`) instead of raw `if`/`t.Fatal` checks.
13* In tests, always use the latest Hugo specification, e.g. for layouts, it's `layouts/page.html` and not `layouts/_default/single.html`, `layouts/list.html` and not `layouts/_default/list.html`
14* Never name tests `TestIssue1234`; always give the test function a descriptive name, e.g. `TestDisablePathToLower`, and add any issue reference as a Go doc function comment, e.g. `// See issue 1234.`.
15* If you borrow a test case (e.g. from the issue), that test's author must be added as co-author in the commit.
16* If you're a security researcher, read @SECURITY.md carefully.
17* Brevity is good. This applies to code, comments and commit messages. Don't write a novel.
18* Use `./check.sh ./somepackage/...` when iterating.
19* Use `./check.sh` when you're done.
20 
21 
22[^1]: CI build fail if you forget to remove the debug printing.
23