sneak/quak
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Mandate TDD in README development workflow

Browse Source 
All changes go on a feature branch; the first commit on the branch is the
failing test suite for the change; the branch can only merge to main when
make check is green. Tests are the canonical API documentation and must be
commented thoroughly so a reader can learn the library from them.
This commit is contained in:
Jeffrey Paul
2026-05-09 21:37:33 +02:00
parent b35c677e23
commit 3ccb00d6c8
1 changed files with 26 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
README.md
View File

@@ -65,6 +65,32 @@ account, decrypt and save files. Upload, sharing, deletion, and bidirectional
sync are out of scope. Adding them later is straightforward; doing them right
requires the protocol layer to be correct first.
## Development workflow
All work on quack is test-driven. No exceptions.
1. Every change starts on a feature branch off `main`.
2. The first commit on the branch is the test suite for what is being added or
changed. Those tests must fail at that commit; the branch is red until the
implementation lands.
3. Subsequent commits add the implementation and any refactors needed to make
the tests pass.
4. A feature branch can only be merged into `main` when `make check` is green.
`main` is always green. The Dockerfile runs `make check`, so a red branch
cannot pass CI.
5. Tests are the canonical API documentation for this library. Every test file
is commented thoroughly enough that a reader who has never seen quack can
learn how to use it from the tests alone. Comments explain why a behavior
matters, not just what the assertion checks.
6. Test fixtures (cryptographic vectors, recorded HTTP responses, sample files)
are committed alongside their tests. Where possible they are generated by
deterministic helpers in the `test/` tree so any reviewer can reproduce them
by running the helper.
7. `git rebase -i` is allowed on a feature branch before merge to clean up the
test-then-implementation sequence into reviewable commits, but the final
history must still show tests landing before (or with) the matching
implementation.
## Design
quack is a TypeScript library with a thin CLI wrapper. The library does the