amr/passepartout
1
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: enforce TDD red-green-refactor discipline in CONTRIBUTING
Some checks failed
Deploy (Gitea) / deploy (push) Failing after 3s
Details

Browse Source
This commit is contained in:
Amr Gharbeia
2026-05-05 09:08:28 -04:00
parent d782f58291
commit 94b939f61a
1 changed files with 23 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/CONTRIBUTING.org
View File

@@ -6,6 +6,23 @@
* Philosophy * Philosophy
Passepartout is built on a "Zero-Bloat" mandate. The core kernel is mathematically pure, pushing all peripheral logic, API integrations, and routing to hot-reloadable "Skills". Passepartout is built on a "Zero-Bloat" mandate. The core kernel is mathematically pure, pushing all peripheral logic, API integrations, and routing to hot-reloadable "Skills".
* TDD Discipline (Red-Green-Refactor)
All code changes MUST follow this cycle:
1. *Write a failing test* — capture the desired behavior as a FiveAM test
in a =* Test Suite= section within the relevant =.org= file
2. *Prove it fails* — run =sbcl --eval "(asdf:test-system :passepartout)"=
and confirm the new test fails (RED) before writing implementation
3. *Write the code* — modify the implementation in the same =.org= file
4. *Prove it passes* — run the test suite again, confirm GREEN
5. *Reflect* — ensure the test and code are both in the =.org= literate source
For *existing code* that lacks tests: write a characterization test that
captures current behavior as the spec. Then refactor.
No test may be committed without proof it was first run to failure.
* Literate Granularity * Literate Granularity
We strictly adhere to Literate Programming using Org-mode. We strictly adhere to Literate Programming using Org-mode.
- *Never* edit `.lisp` files in `src/` directly. - *Never* edit `.lisp` files in `src/` directly.
@@ -37,8 +54,9 @@ All inter-process communication occurs via the Unified Envelope. Do not use lega
- Ensure generated `:REQUEST` messages include a mandatory `:TARGET` field. - Ensure generated `:REQUEST` messages include a mandatory `:TARGET` field.
* Pull Request Process * Pull Request Process
1. Ensure your working tree is clean. 1. Choose an Org file and write a failing test in its =* Test Suite= section.
2. Write tests for your skill in `tests/`. 2. Tangle and run to confirm RED (the test fails).
3. Tangle all files. 3. Write the implementation in the same Org file, tangle, run to confirm GREEN.
4. Run the test suite: `sbcl --eval "(asdf:test-system :passepartout)"`. 4. Ensure your working tree is clean.
5. Submit a PR outlining the architectural intent and the specific Literate changes. 5. Run the full test suite: =sbcl --eval "(asdf:test-system :passepartout)"=.
6. Submit a PR outlining the architectural intent and the specific Literate changes.