From dddf5df14a4f0b48bbf55e46227aafe7dafef296 Mon Sep 17 00:00:00 2001 From: Christian Heimes Date: Tue, 12 May 2026 14:11:03 +0200 Subject: [PATCH] docs(agents): add rules for DCO sign-off, `.test` TLD, backtick formatting, and Sphinx version directives - enforce `git commit --signoff` for DCO sign-off (agent was sometimes ignoring the rule) - use `.test` TLD instead of `example.com` in tests and examples - use single backticks in markdown/commit messages, double backticks in .rst - use Sphinx `versionadded`/`versionremoved`/`versionchanged` directives for user-facing changes Co-Authored-By: Claude Signed-off-by: Christian Heimes --- AGENTS.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 095c0f50..4a38d34e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,6 +15,7 @@ - Chain exceptions: `raise ValueError(...) from err` - Use `req_ctxvar_context()` for per-requirement logging - Run `hatch run lint:fix` to format code +- Always use `git commit --signoff` ### Don't @@ -93,16 +94,25 @@ Look at these before writing code: **Import rules:** All imports at the top of the file, no local imports. See [CONTRIBUTING.md](CONTRIBUTING.md) for details. +**URLs:** Use the `.test` TLD (e.g. `https://pkg.test/simple/`) instead of `example.com` in tests. Use `.example` TLD in examples. + **Testing:** Use Arrange/Act/Assert pattern, name functions `test_()`. See `tests/test_context.py` for examples. +## Documentation and doc strings + +- Use single backticks around function and class names in markdown (e.g. `req_ctxvar_context()`, `WorkContext`), double backticks in .rst (reStructuredText) +- Use Sphinx `versionadded`, `versionremoved`, `versionchanged` directives for user-facing changes (get next version from last git tag) + ## Commit Messages Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) — see [CONTRIBUTING.md](CONTRIBUTING.md) for format, types, and examples. -When AI agents create or significantly modify code, add attribution: +Use backticks around function and class names (e.g. `WorkContext`) + +Always use `--signoff` to add a DCO sign-off. When AI agents create or significantly modify code, also add attribution: ```text -feat(scope): short summary +git commit --signoff -m "feat(scope): short summary Body explaining what and why. @@ -110,6 +120,8 @@ Co-Authored-By: Claude Closes: #123 ``` +This produces a commit message with both the `Signed-off-by` trailer (from `--signoff`) and the `Co-Authored-By` trailer. + ## Workflow for Complex Tasks 1. **Search codebase** for similar patterns first