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 says what zig-astro is and how it is used.

Where to send changes #

Report issues and send pull requests to the Tangled mirror: https://tangled.org/jcollie.dev/zig-astro.

Setting up #

Everything is pinned in the Nix flake, Zig 0.17.0 included:

$ 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:

$ 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. 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.