# Contributing to zig-astro Thank you for wanting to help. This file covers what you need to know to make a change and get it accepted. [README.md](README.md) says what zig-astro is and how it is used. ## Where to send changes Report issues and send pull requests to the Tangled mirror: . ## Setting up Everything is pinned in the Nix flake, Zig 0.17.0 included: ```console $ git clone https://git.jcollie.dev/jeff/zig-astro.git $ cd zig-astro $ nix develop ``` The development shell has `zig`, `reuse`, `git-pages-cli` and, on Linux, `kcov`. Without Nix, you need Zig 0.17.0 and nothing else: the library has no dependencies. ## Before you send a change CI runs these, and a change has to pass all of them: ```console $ reuse lint # every file has a license $ zig fmt --exclude zig-pkg --check . # Zig is formatted $ zig build test --summary all # the tests $ zig build check # everything compiles ``` `zig build docs` should also succeed, since the documentation is published from `main` once the tests pass. ## Where things are | Path | What | | --- | --- | | `src/root.zig` | The root of the `astro` module | | `src/time.zig` | `astro.time`: instants, time scales, calendars and ΔT | | `src/Angle.zig` | `astro.Angle`: angles in every unit | | `src/coord.zig` | `astro.coord`: ecliptic, equatorial and horizontal coordinates | | `src/earth.zig` | `astro.earth`: nutation, the obliquity of the ecliptic, and sidereal time | | `src/observer.zig` | `astro.observer`: an observer on the Earth, topocentric positions, and refraction | | `src/sun.zig` | `astro.sun`: the Sun's apparent position | | `src/moon.zig` | `astro.moon`: what the Moon exports | | `src/moon/` | The Moon's calculations, one file each | | `tests/` | Tests of the public API: worked examples, reference tables, and properties | | `tests/fuzz.zig` | Fuzz targets, which are also ordinary tests on their seeds | | `tests/reference/` | Ephemerides from JPL Horizons, exactly as Horizons sent them, and NASA's table of the phases of the Moon | | `tests/horizons.zig` | Reads those tables for the tests | | `tools/horizons.sh` | The queries that fetch them: `tools/horizons.sh all` | | `tools/nasa-phases.sh` | Fetches and converts NASA's table of the phases of 1901–2100 | | `tools/docs_server.zig` | The local server behind `zig build docs-serve` | | `GLOSSARY.md` | The project's vocabulary: use its terms, and add to it when a new one is settled | | `docs/adr/` | Decisions worth remembering the reasons for | ## Making changes ### Sources Every calculation names where it came from: the book, paper or standard, and the chapter, section or equation. Put that in the doc comment of the function that implements it, and add the source to the references cited in `README.md`. ### Transcribing tables Coefficients and worked-example values are read from the page images of the book, not from OCR text, which misreads digits. Where a table can be checked as a whole — by a worked example that uses every term, or by a bound such as the sum of its coefficients — check it that way too. ### Tests Every behavior change comes with a test. Where the source gives a worked example, test against it and cite the example beside the test, and say what tolerance the comparison uses and why. Tests go through the public API only: they live in `tests/`, in a module that imports `astro` the way a consumer does. Every new calculation also gets a fuzz target in `tests/fuzz.zig` showing that no `f64` makes it panic, that a NaN or infinite instant gives NaN, and that finite results stay in their documented ranges. `zig build fuzz --fuzz=100K` is a short run; leave it going without a limit to search. ### Reference tables A calculation that can be checked against JPL Horizons is. Add the target to `tools/horizons.sh`, run it, and commit what it writes to `tests/reference/` without editing it. Hold each quantity to the accuracy the source states for the method; where the source states none, measure the largest error over the table, say what it was in a comment, and set the tolerance just above it. Never set a tolerance before measuring. ### Errors Input outside a calculation's domain is an error or a documented result, never a panic. ### Documentation A public declaration gets a doc comment, which is what the published API documentation is made from. Say what units every argument and result is in, and which time scale and reference frame a value belongs to. When behavior changes, update `README.md` to describe how things are now, not how they changed. ## Licensing zig-astro is MIT licensed and follows [REUSE](https://reuse.software/). Every new file starts with an SPDX header like the ones already in the tree; a file that cannot hold one goes in `REUSE.toml`. By sending a change you agree to license it under the MIT license. ## Commits The first line is a short summary in the imperative ("add the lunar phase"). The body explains what changed and why.