Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
202 lines (156 loc) · 8.08 KB

CONTRIBUTING.md

File metadata and controls

202 lines (156 loc) · 8.08 KB
Raw

Contributing

Contributions are welcome. Useful changes include bug fixes, focused features, hardware compatibility, documentation, tests, and new bird plates for the reusable catalog.

Before starting

  • Search existing issues and pull requests.
  • Open a feature request before a change that affects architecture, catalog policy, external APIs, configuration compatibility, or a major dependency.
  • Use the bird request template to claim a species before investing in a new plate. This helps avoid duplicate generation work.
  • Use the published plate problem template for a concrete factual, visual, or readability issue in an approved catalog plate.
  • Report vulnerabilities privately as described in SECURITY.md.

Development setup

Use Python 3.11 or newer and uv:

git clone https://github.com/veteranbv/inky-bird-frame.git
cd inky-bird-frame
uv sync --extra dev --locked

Run the application from the managed environment:

uv run inky-bird-frame --help

To test the controller container built from your checkout, add the source-build override explicitly:

docker compose -f compose.yaml -f compose.build.yaml build --pull

The default compose.yaml pulls the published image and is the normal user path. It never builds local source by itself.

Private controller configuration is not required for unit tests or catalog validation. Never commit a real config.toml, notification destination, observation snapshot, downloaded reference image, generated run directory, or authentication material.

Engineering expectations

  • Keep changes small, coherent, and directly related to the stated problem.
  • Prefer existing modules and patterns over new layers or dependencies.
  • Do not submit stubs, fake implementations, hidden fallbacks, or unexplained hardcoded values.
  • Preserve the controller/display-node boundary. The display node consumes the approved HTTP catalog and does not perform discovery or generation.
  • Use typed models and structured parsers for external data. Avoid untyped dictionaries at module boundaries.
  • Keep CLI success and failure output in the existing JSON envelope.
  • Treat network services, Codex, GitHub, notifications, and display hardware as explicit boundaries with bounded failures and useful errors.
  • Maintain compatibility for documented configuration unless the change includes a clear migration.
  • Add focused tests for behavior changes and regression tests for bug fixes.

Tests must not require network access, Codex authentication, notification credentials, or Inky hardware. Mock those boundaries and keep fixtures location-neutral.

Code changes

  1. Create a focused branch in your fork.
  2. Implement the smallest complete change.
  3. Update documentation and config.example.toml when public behavior or configuration changes.
  4. Run the project checks.
  5. Open a pull request and complete the applicable template sections.

Required checks:

uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest
uv run inky-bird-frame catalog validate --catalog catalog

Run uv run ruff format . before the checks when Python files need formatting. CI also validates GitHub Actions and shell deployment scripts.

Catalog contributions

Catalog entries are immutable, location-neutral artifacts. A contribution adds one new taxon; it must not edit or replace an approved taxon.

Generate and prepare a plate

Generate and approve the plate using your own controller and Codex account. Then, from a checkout of your fork, copy exactly one approved taxon into the public catalog:

uv run inky-bird-frame catalog prepare <taxon-id> \
  --source-catalog <approved-catalog> \
  --catalog catalog

uv run inky-bird-frame catalog validate --catalog catalog

catalog prepare validates the complete source catalog, copies only the requested taxon, rebuilds catalog/index.json, and validates the result. It fails if the source taxon is missing or conflicts with an existing entry. Do not hand-edit generated JSON or checksums.

Correct a published plate

Published taxa remain immutable by default. After a replacement has completed the controller's explicit human-review workflow, a maintainer can prepare the approved correction with a required reason:

Before proposing a replacement, open a published plate problem with the exact plate and supporting evidence. Do not upload copyrighted field-guide or reference images.

uv run inky-bird-frame catalog prepare <taxon-id> \
  --source-catalog <approved-catalog> \
  --catalog catalog \
  --replace-approved \
  --reason "Human-reviewed reason for replacing the published plate"

The command verifies that the taxon identity is unchanged, records the prior approval timestamp and image hashes in catalog_migration, preserves earlier reviewed replacements as migration history, replaces the entry transactionally, rebuilds the index, and validates the result. Pull-request CI accepts the replacement only when the newest record exactly matches the base catalog. Ordinary catalog contributions remain add-only. Controller catalog sync accepts the recorded ancestry only when deployment explicitly enables reviewed migrations, so an installation may safely skip intermediate releases. A validated destination descendant is retained; catalog sync never downgrades it.

Required plate contents

Each catalog/species/<taxon-id>-<slug>/ directory contains only the files allowed by the catalog validator:

  • portrait.png: metadata-free 1200x1600 PNG;
  • display.png: metadata-free 1600x1200 PNG;
  • manifest.json: identity, facts, sources, provenance, generation metadata, review, and matching SHA-256 checksums;
  • profile.json: factual species profile matching the manifest, when produced by the current pipeline; and
  • quality-review.json: sourced review matching the manifest, when produced by the current pipeline.

The contribution must not contain discovery locations, observation counts, local paths, private service addresses, credentials, run logs, or downloaded reference images. Source URLs and reference licensing or provenance remain in the metadata, but source bitmaps are not redistributed.

You must have the right to submit the generated images and metadata under the repository's MIT license. Do not submit copyrighted field-guide artwork or reference photographs as catalog assets.

Catalog review

Public CI checks the file allowlist, schema, checksums, image dimensions, embedded image metadata, private fields, provenance requirements, quality review thresholds, index consistency, and add-only behavior against the pull request base.

A submitted quality-review.json is evidence from the contributor's pipeline, not a substitute for maintainer-side verification. Maintainers may run an independent, sourced review of the committed artifacts before acceptance. A trusted reviewer must treat pull request files as data and must never execute a contributor branch on the private controller.

Pull request review

Pull requests should explain the user-visible behavior, validation performed, security or compatibility implications, and anything that could not be tested. Review findings should be resolved on the same pull request so the complete change remains visible to reviewers.

All pull requests must pass formatting, lint, strict typing, tests, catalog validation, and the repository review gate. The repository owner controls the exact-head Codex review request and production deployment. External pull requests never receive those credentials.

For a draft pull request, mark it ready before the owner's final exact-head Codex review request. The ready-for-review transition invalidates review signals from the draft lifecycle; wait for the post-ready review gate to finish before merging or enabling auto-merge.

Documentation and agent guidance

Public documentation and examples must be portable. Use placeholders for locations, hosts, URLs, usernames, and secrets. AGENTS.md contains public project-wide guidance for coding agents; update it only when a durable project rule changes, and keep detailed procedures in the relevant documentation.