docs: centralise test counts + add release-policy + remove stale stub references

Two complementary improvements aimed at reducing recurring maintenance
overhead:

1. **Test-count centralisation** — `doc/api/tests.md` is now the
   single source of truth for the test counts.  All other docs
   (README, CLAUDE.md, doc/contributing.md, doc/getting-started.md,
   doc/math/validation.md, doc/math/validation-protocol.md,
   scripts/try_it.sh) use qualitative phrasing + a link instead of
   hardcoded numbers.  The previous regime had eight places with
   "227 CGAL tests, 23 non-CGAL tests" that drifted apart across
   releases (the v0.9.0 release-prep needed to touch nine files).

2. **Versioning policy** — `doc/release-policy.md` (new, ~250 lines)
   formalises:
   * SemVer rules for the pre-1.0 and post-1.0 phases.
   * Phase-milestone → MINOR-bump mapping (v0.10.0 → Phase 9c, …).
   * Single-source-of-truth table for moving numbers (test counts,
     version, date).
   * Step-by-step release process (the recipe that worked for v0.9.0
     after the false-start with PR #11/#12).
   * Hotfix policy + post-1.0 deprecation policy.
   * Known failure modes and how to recover from them.

Plus a small CI gate:

3. **scripts/check-test-counts.sh** — verifies the totals in
   doc/api/tests.md match `ctest` output.  Re-uses existing build-cgal/
   if present.  Exit 0 on match, 1 on divergence with recovery hints.
   Cheap enough (~30 s) to run on every PR.

Other cleanups
──────────────
* code/tests/cgal/CMakeLists.txt — stale "Test 7 (genus-2 homology)
  as GTEST_SKIP stub until Phase 8" comment removed; that test landed
  as HomologyGenerators.Genus2_FourCutEdges in Phase 7.
* CLAUDE.md — "test-fast also runs stubs" Known Quirks entry updated
  to reflect the v0.9.0 stub cleanup (no GTEST_SKIPs remain).
* CLAUDE.md doc map — new entry for doc/release-policy.md.

Stubs audit
───────────
Zero GTEST_SKIP() calls remain in the codebase as of this commit.
The only references to stubs are in historical documentation
(CHANGELOG.md v0.7.0 entry, doc/roadmap/* "deferred to research-track"
notes) — those are intended.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tarik Moussa
2026-05-22 07:59:10 +02:00
parent e67ccd6b9d
commit 0f78d181e1
10 changed files with 326 additions and 17 deletions

View File

@@ -199,7 +199,7 @@ inner/outer edge lengths). Use `torus_8x8.off` for a finer approximation.
## Summary checklist
```
[ ] Check 0: 176 tests pass, 0 skipped
[ ] Check 0: full test suite passes, 0 skipped (counts: `doc/api/tests.md`)
[ ] Check 1: GaussBonnet exact (1e-10)
[ ] Check 2: FD gradient < 1e-6 for all 3 geometries
[ ] Check 3: Newton convergence < 50 iterations

View File

@@ -14,7 +14,7 @@ cmake --build build --target conformallab_cgal_tests
ctest --test-dir build -R cgal --output-on-failure
```
All 227 tests pass, 0 skipped (see `doc/api/tests.md`).
All tests pass, 0 skipped (per-suite breakdown: `doc/api/tests.md`).
---
@@ -252,7 +252,7 @@ implemented in conformallab++ (→ GC-2 in the phase roadmap).
Run these in order to validate the implementation:
- [ ] `ctest --test-dir build -R cgal --output-on-failure`227 tests pass, 0 skipped
- [ ] `ctest --test-dir build -R cgal --output-on-failure`all pass, 0 skipped (count: `doc/api/tests.md`)
- [ ] `cgal.GaussBonnet.*` all pass → topology is correctly read from mesh
- [ ] `cgal.EuclideanFunctional.GradientCheck_*` pass → energy = integral of gradient
- [ ] `cgal.PeriodMatrix.TauInFundamentalDomain_*` pass → SL(2,) reduction correct