Contributing

Thank you. This page is the short form; the repository’s CONTRIBUTING.md holds the git workflow and CLAUDE.md the engineering rules that apply to every contributor, human or otherwise.

Getting the source

git clone https://github.com/oddurs/fontina
cd fontina
cargo build
cargo test
cargo clippy --all-targets -- -D warnings

Rust 1.88 or newer. Set FONTINA_DB=/tmp/u.db while developing so you do not touch your real index.

Repository layout

crates/fontina-core       parsing, metadata model, SQLite index, scan, CSS export,
                          health checks, HTML specimen
crates/fontina-platform   per-OS font directories and the FontActivator trait
crates/fontina-cli        the `fontina` binary
schemas/                  JSON Schemas; regenerated with `fontina schema <name>`
fixtures/                 OFL-licensed test fonts, kept small
docs/adr/                 architecture decision records
site/                     this web site

Rules that are not negotiable

• Never modify system font directories or require elevation. Per-user only.
• No network calls in the core or the command line. No telemetry of any kind.
• Parsing goes through fontations. Do not hand-parse a table it already exposes.
• Standards over invention: CSS Fonts Level 4, SPDX, XDG, JSON Schema, TOML.
• Errors are values. The core never panics on font input.
• Every new dependency needs a stated reason.

Workflow

Trunk-based. main is protected and every change is a pull request that GitHub merges once the required checks pass: format and clippy, tests on three operating systems, the minimum supported Rust version, license and advisory auditing, a check that the JSON Schemas are current, the Linux distribution matrix, the packaging tests, the fuzz corpus, and the performance budgets.

git checkout -b feat/<topic> main
# make the change; run cargo test and clippy
git commit -m "feat(core): <what and why>"
gh pr create --fill
gh pr merge --auto --squash --delete-branch

Commit messages follow Conventional Commits with the crate as scope: feat(core), fix(cli), docs, ci. The pull request title becomes the squash commit subject. No Co-Authored-By or tool trailers. release-please turns the history into the changelog and the version bump; nothing is released by hand.

What a good change looks like

• One logical change per pull request. Split refactors from features.
• A new parsed capability comes with a fixture font (open license, under 500 KB, source noted in fixtures/README.md) and a snapshot test.
• A new health check has a stable area/check identifier that is never renamed, and a fixture-backed test that triggers it.
• A change to a public type in the metadata model regenerates the schemas and, if not backwards compatible, bumps the schema version.
• Database changes are append-only migrations. Applied migrations are never edited.
• A decision worth arguing about gets an architecture decision record.

Licensing of contributions

By contributing you agree your work is licensed GPL-3.0-or-later, matching the project, without any additional terms. There is no contributor license agreement to sign and no copyright assignment: you keep your copyright, which is what makes the license hard for any single party to revoke later. The license page has the reasoning.

Conduct

The project follows the Contributor Covenant.