docs: add AGENTS.md and CONTRIBUTING.md conventions

2026-08-28 19:32:29 -04:00
parent 1685eff2df
commit ea9ca79d48
2 changed files with 108 additions and 0 deletions
@@ -0,0 +1,56 @@
+# Contributing to stupidtools
+
+The project is a GNU AutoTools replacement: read a KDL build file, emit a
+POSIX-sh `./configure`. Contributions should follow the rules in AGENTS.md.
+This file covers the mechanics.
+
+## Build
+
+stupidtools bootstraps itself with autotools:
+
+```
+autoreconf -ivf
+./configure
+make
+```
+
+You need a C23-capable compiler (GCC >= 14 or Clang >= 18) and autotools.
+The build compiles with `-std=c23 -Wall -Wextra -Wpedantic`.
+
+## Test
+
+```
+make check      # unit tests via the vendored single-header C test framework
+tests/run.sh    # shell integration tests (exact exit codes + grep-able markers)
+```
+
+TDD workflow: write the test alongside the code. Implementation + test is one
+unit of work, never separated.
+
+## Commit
+
+Conventional commits, one per logical change:
+
+- `build:` build system, toolchain flags
+- `feat(kdl):` lexer, parser, values, schema
+- `feat(detect):` check registry, probes, feature resolution
+- `feat(gen):` configure generator, config.status/log/h, argument parsing
+- `feat(ext):` extension ABI, Lua embed, discovery
+- `test:` tests
+- `docs:` documentation
+- `chore:` vendoring, misc
+
+Never bundle two logical changes in one commit. Never commit generated
+artifacts (`configure`, `Makefile`, `config.h`, `config.status`, `config.log`).
+
+## Vendoring policy
+
+Every third-party library is vendored in-tree under `thirdparty/<name>/`:
+
+- the upstream `LICENSE` file (never omitted, never stubbed),
+- an `UPSTREAM` file recording the source URL and the pinned upstream commit
+  SHA,
+- a row in the `thirdparty/README.md` provenance table (name, version, license,
+  SHA).
+
+No git submodules. If it is not vendored this way, it does not exist.