0f78d181e1
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>
87 lines
2.5 KiB
Markdown
87 lines
2.5 KiB
Markdown
# 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:
|
|
```bash
|
|
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:
|
|
|
|
1. **Gradient check** — finite-difference verification of `G(x) = ∂E/∂x`.
|
|
Copy any `GradientCheck_*` test suite from `tests/cgal/test_*_functional.cpp`.
|
|
|
|
2. **Convergence test** — Newton converges on a small mesh using the "natural theta"
|
|
trick (see [CLAUDE.md](../CLAUDE.md) and [api/extending.md](api/extending.md)).
|
|
|
|
3. **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`](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`:
|
|
|
|
```bash
|
|
# 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
|