Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
163 lines (118 loc) · 5.64 KB

CONTRIBUTING.md

File metadata and controls

163 lines (118 loc) · 5.64 KB
Raw

Contributing to Logion

Thanks for your interest in contributing! This guide covers everything you need to set up your environment, make changes, and open a pull request.

Code of Conduct

This project follows the Contributor Covenant v2.1. Please read it before participating.

Filing a bug

Use the Bug Report template. Include the logion --version output, your platform, and clear steps to reproduce.

Proposing a feature

Use the Feature Request template. Significant changes (new commands, API changes, architectural shifts) should start as a Discussion or RFC before turning into a PR.

Contributing to plans and protocol references

The public plans/, future-roadmap/, and protocol-specs/ directories are a generated, contribution-friendly projection of the maintainers' canonical planning source. You may open a normal public PR proposing a concrete edit. Maintainers review it in public, port an accepted patch into the canonical source with attribution, and regenerate the public files and manifest before merge. This keeps one ordered source of truth without hiding product direction or excluding public contributors.

Do not edit an automation sync branch directly. For an independent planning PR, run python3 scripts/check_roadmap_mirror.py --update after editing so reviewers can verify the proposed projection. Acceptance is not final until the canonical sync reproduces the same content.

Files under protocol-specs/upstream/ are byte-for-byte, commit-pinned copies of external normative specifications. Do not edit them as Logion prose. Propose normative changes to the owning upstream project; propose a pin update here only with the upstream diff, compatibility impact, licenses, and refreshed hashes. Run python3 scripts/check_protocol_specs.py to verify snapshot integrity.

Setting up your machine

git clone https://github.com/nicolasmelo1/logion.git
cd logion
uv sync --all-packages --all-groups
make install-hooks
make test

Prerequisites:

  • Python 3.12+
  • uv — package and workspace manager
  • Node.js 18+ (only needed for the Prism mock server)
  • Rust/Cargo (for make factory-check; the first run builds the reviewed sf revision)

make factory-check and CI use python3 scripts/sf.py, which installs the commit pinned in that launcher under .local/software-factory/ without replacing a global sf. It checks Cargo source provenance and the installed binary's recorded SHA-256 before each invocation; an unrelated sf on PATH is never used. A missing install needs network access; a damaged or unverifiable install fails closed with its rebuild path. Do not remove rule documentation to accommodate a different local tool version.

Running the OpenAPI mock locally

The Logion API contract is in contracts/openapi/v1.json. You can spin up a mock server that serves realistic responses directly from it:

make mock          # starts Prism on port 4010
make mock-stop     # stops the mock server

See docs/openapi-sync.md for details on how the contract is synced and why contributors should not edit it directly.

Submitting a PR

Branch naming

  • feat/<short-description> — new features
  • fix/<short-description> — bug fixes
  • docs/<short-description> — documentation
  • chore/<short-description> — maintenance, tooling, dependencies

Commit messages (required)

This project uses Conventional Commits because the release automation (based on python-semantic-release) parses commit history to determine version bumps. Every commit message must follow the format:

type(scope)!: summary

Common types: feat, fix, docs, refactor, test, chore, perf, ci, build.

The ! (breaking change marker) and (scope) are optional.

Examples:

feat(cli): add listings export command
fix(client): handle 404 in course lookups
docs: clarify mock-server setup in CONTRIBUTING
chore(deps): bump ruff to 0.5.0

Sign-off (DCO)

Every commit must be signed off:

git commit -s

This adds a Signed-off-by: trailer that certifies you wrote or have the right to submit the patch (Developer Certificate of Origin).

PR checklist

When you open a PR, the template will ask you to confirm:

  • make lint passes
  • make test passes
  • Any area-specific checks (e.g. make typecheck)
  • Backwards compatibility (or a migration plan)
  • PR title follows Conventional Commits

Where the contract comes from

contracts/openapi/v1.json is generated by an internal service and synced into this repo on merges to main. You will see PRs labeled automation/sync-openapi — these are produced by CI.

Contributors cannot modify contracts/openapi/v1.json directly. If you need a change to the API surface (new endpoint, changed schema, etc.), open a Discussion to propose it. The maintainers will evaluate and implement it upstream if accepted.

See docs/openapi-sync.md for details on how the contract is synced and how to work with the mock server.

Release process

Releases are automated via python-semantic-release. See the release workflow documentation (planned: RELEASING.md) for details on how version bumps, changelog generation, and package publishing work.

Questions? Open an issue or start a Discussion.