# Contributing to cosmos-validation

Thanks for taking an interest. This document lays out the small set of
conventions that keep `cosmos-validation` useful as the gating
harness for the wider `eternal-*` workspace.

## How the harness works

Every feature ships with three pieces:

1. **A pure-Rust module** under `src/` implementing the calculation.
2. **A Swiss-Ephemeris (or JPL Horizons) reference fixture** under
   `fixtures/`, generated by a reproducible script under `scripts/` or
   by `precision-report fetch`.
3. **An inspection CLI** under `src/bin/<feature>_check.rs` that prints
   a per-fixture diff table.

The integration test `tests/regression.rs` walks every fixture in
`fixtures/regression-*/` (kernel-scoped) and asserts the per-fixture
tolerances on CI.

## Filing an issue

Before opening an issue, please run the relevant `*-check` binary and
include the diff table. The numbers it prints are far more useful than
a screenshot or a textual summary.

For precision regressions, also include:

- Kernel file path and SHA-256 (`sha256sum ~/.local/share/ephemeris/de440.bsp`).
- Swiss Ephemeris version (`swisseph.version` from Python).
- Your platform (`uname -a`, `rustc --version`).

## Opening a pull request

### Validation first

Every new module or feature must:

- Add a Swiss-Ephemeris reference fixture (preferred) or a JPL Horizons
  fixture in `fixtures/`.
- Add or extend the corresponding `scripts/fetch_swiss_*.py` so others
  can regenerate the fixture.
- Add an inspection CLI under `src/bin/<feature>_check.rs` that prints a
  diff table in the same style as the existing ones.
- Update **PRECISION.md** with the measured precision row.
- Update **CHANGELOG.md** under `[Unreleased]` with the new feature.

### Precision-budget commits

When you tighten or loosen a tolerance:

- Document the tolerance change in the commit message.
- If the residual moved because of a known algorithmic difference, link
  the relevant Swiss-Ephemeris source file or NAIF/IAU paper in the
  commit body.
- Avoid relaxing a `regression-*` tolerance silently — if a residual
  grew, explain why, ideally with a reproduction in the message.

### No silent fall-backs

If the local code cannot reproduce a Swiss / Horizons answer, log the
discrepancy explicitly in the inspection CLI and document the cause in
[PRECISION.md → Known limitations](./PRECISION.md#known-limitations).
Do **not** mask gaps by relaxing the comparison tolerance.

### Commit style

The repository follows a "topic per commit" convention (no merge
commits, no `git rebase --autosquash`). Commit messages are
imperative, ~70 chars on the first line, with a body describing the
*why*:

```
Wire stellar aberration (Phase 2 step 2)

Extend the SPK oracle with apparent-vector computation: take the
astrometric position vector from step 1, derive the observer's
…
```

Co-authoring is welcome. Add a `Co-Authored-By:` trailer if you pair
or use an assistant.

### CI / release

`cosmos-validation` is `publish = false`. There is no `cargo publish`
gate. The release artefact is the workspace itself; cutting a release
means tagging the workspace and updating the workspace version in the
root `Cargo.toml`.

## Code of conduct

Be respectful. Disagreement on technical points is welcome; personal
attacks are not. We follow the
[Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct)
as a baseline.

## License

By contributing you agree that your contribution is licensed under the
**Apache License, Version 2.0**, matching the rest of the workspace
(see [LICENSE-APACHE](../LICENSE-APACHE) and [NOTICE](../NOTICE)).
