Tarik Moussa
a2464af8b1
Add a lightweight test-fast pipeline for the public Codeberg mirror so it shows a build status, defined for both CI systems Codeberg offers: - .woodpecker.yml (Woodpecker, debian:bookworm) - .forgejo/workflows/ (Forgejo Actions, node:20-bookworm, runner label docker) Both run the pure-math suite only (Eigen vendored, GTest via FetchContent; no CGAL/Boost), using public images and the docker runner label since the private eulernest ci-cpp image and Pi runner are unreachable from Codeberg. Docs: - new doc/architecture/ci-cd.md: two-forge topology, runners, trigger keywords, mirror mechanism. - fix stale "codeberg/main ... no CI" claim in contributing.md and bring the CI table up to date. - link the new doc from the README doc index. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
101 lines
3.3 KiB
Markdown
101 lines
3.3 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` is the public mirror. It now also runs CI of its own
|
|
(Woodpecker + Forgejo Actions) — see [architecture/ci-cd.md](architecture/ci-cd.md).
|
|
- Both remotes must stay in sync after every significant change:
|
|
```bash
|
|
git push origin HEAD:dev # triggers eulernest CI (full suite, keyword-gated CGAL)
|
|
git push codeberg main # updates public mirror → triggers Codeberg CI (test-fast)
|
|
```
|
|
- Branch naming: `feature/<topic>`, `fix/<topic>`, `phase<N>-<topic>`
|
|
|
|
---
|
|
|
|
## CI
|
|
|
|
The project runs CI on **two forges**. Full topology, runners, images and
|
|
trigger keywords are documented in [architecture/ci-cd.md](architecture/ci-cd.md).
|
|
|
|
**eulernest Gitea** (`origin`, self-hosted Raspberry Pi / ARM64) — the
|
|
authoritative gate. On push to `dev`/`main` or a pull request:
|
|
|
|
| Job | What it tests | Trigger |
|
|
|---|---|---|
|
|
| `test-fast` | pure-math tests, no Boost | all branches |
|
|
| `test-cgal` | full CGAL test suite | commit message contains `/test-cgal` |
|
|
| `quality-gates` | license / codespell / shellcheck / CGAL conventions | commit message contains `/quality-gates` |
|
|
|
|
A PR is ready to merge when `test-fast` (and, for CGAL-touching work,
|
|
`test-cgal`) pass. See `.gitea/workflows/cpp-tests.yml` and
|
|
`.gitea/docker/Dockerfile.ci-cpp`.
|
|
|
|
**Codeberg** (`codeberg`, public mirror, shared runners) — a lightweight
|
|
`test-fast` mirror so the public repo also shows a build status. Defined twice,
|
|
once per CI system Codeberg offers:
|
|
|
|
| File | CI system |
|
|
|---|---|
|
|
| `.woodpecker.yml` | Woodpecker CI (ci.codeberg.org) |
|
|
| `.forgejo/workflows/cpp-tests.yml` | Forgejo Actions |
|
|
|
|
---
|
|
|
|
## 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
|