Skip to content

Contributing

We love contributions. Here's how to land one cleanly.

1. Open an issue first

For non-trivial changes, file an issue with:

  • User story — "As a … I want … so that …".
  • Context diagram — a small mermaid block.
  • Success criteria — bulleted, testable.
  • Job size — S / M / L.
  • Tags — tool, docs, infra, bug, etc.

This is for the maintainer's benefit and yours — surfacing the "what" before the "how" saves rework.

2. Branch + dev shell

git switch -c feat/<short-name>
nix develop

3. Write the change

  • Keep PRs small — one concept at a time.
  • New tool → new tests → new docs. All three, same PR.
  • Update SPECIFICATION.md if user-visible behaviour changes.
  • Update PACKAGES.md if dependencies change.

4. Verify

nix run .#format
nix run .#test
nix run .#build

All three green.

5. Commit

Conventional-style messages are preferred:

feat(tools): add convex_hull tool

Adds a new MCP tool that returns the convex hull of a GeoJSON
PointCollection. Includes table-driven tests and reference docs.

Fixes #42

6. PR

Open a PR. Reference the issue with Fixes #N so GitHub closes it on merge. The PR description should mirror the issue's success criteria as a checklist.

7. Review

A maintainer will:

  • Run the suite locally.
  • Read the diff for correctness, brand fit, and "would the LLM use this well?".
  • Suggest changes inline.

Once approved, the PR squashes into main. CI cuts a tagged release on the next minor bump.

What we don't merge

  • Breaking changes without a major-version bump path.
  • New tools without tests.
  • New tools without docs.
  • Code that pushes hard-coded /nix/store/ paths into source.
  • Commits with --no-verify set.

Code of conduct

Be kind. Assume good faith. If you wouldn't say it in person in a Kartoza office, don't write it in a PR.