Files

Tarik Moussa 0f78d181e1 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>

2026-05-22 13:24:37 +02:00

2.5 KiB

Raw Blame History

Contributing

Language

All code, comments, documentation, commit messages, and test descriptions must be in English.

The project targets CGAL submission and international collaboration. When editing files that still contain German-language comments or documentation, replace them with English.

Git workflow

main is protected on origin (Gitea). Push to dev, then open a pull request.
codeberg/main can be pushed to directly (public mirror, no CI).

Both remotes must stay in sync after every significant change:

git push origin HEAD:dev   # triggers CI
git push codeberg main     # updates public mirror

Branch naming: feature/<topic>, fix/<topic>, phase<N>-<topic>

CI

Two jobs run on push to dev/main or on pull requests:

Job	What it tests	Trigger
`test-fast`	pure-math tests, no Boost	all branches
`test-cgal`	full CGAL test suite	`main`, `dev`, PRs only

A PR is ready to merge when both jobs pass.

The runner is a self-hosted Raspberry Pi (ARM64). See .gitea/workflows/cpp-tests.yml and .gitea/docker/Dockerfile.ci-cpp.

Test standards

Every new algorithm needs:

Gradient check — finite-difference verification of G(x) = ∂E/∂x. Copy any GradientCheck_* test suite from tests/cgal/test_*_functional.cpp.
Convergence test — Newton converges on a small mesh using the "natural theta" trick (see CLAUDE.md and api/extending.md).
Registration — add the .cpp file to code/tests/cgal/CMakeLists.txt.

Expected CI result: full test suite passing, 0 skipped (per-suite counts: doc/api/tests.md).

Code style

C++17. Header-only (code/include/*.hpp). No compiled library.
#pragma once at the top of every header.
Everything in the conformallab namespace, internal helpers in conformallab::detail.
Property map names follow the prefix convention: "v:" (vertex), "e:" (edge), "f:" (face).
DOF index -1 always means "pinned/fixed".

Releases

Release tags follow vMAJOR.MINOR.PATCH:

# Merge dev → main, then tag
git checkout main && git merge --no-ff dev
git tag -a vX.Y.Z -m "vX.Y.Z — <one-line summary>"
git push origin main && git push origin vX.Y.Z
git push codeberg main && git push codeberg vX.Y.Z

TODO

Define code review checklist
Add .clang-format configuration
Document how to request CGAL package review

2.5 KiB Raw Blame History