# 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