# Contributing to FablePool Kite Map

Thanks for helping kite flyers everywhere! This guide covers code, docs,
translations, and **spot data** contributions. Please also read our
[Code of Conduct](CODE_OF_CONDUCT.md) and the
[Project Charter](docs/09-charter.md) — especially the licensing section,
since your contributions are accepted under those terms.

## 1. Ways to contribute

| Contribution | Where | License you grant |
|---|---|---|
| Backend / frontend / infra code | Pull request | MIT |
| Design docs, rubric text, translations of docs | Pull request | CC BY 4.0 |
| Kite spots, hazard info, condition reports | In-app, or `data/seeds/` PR | ODbL 1.0 |
| Bug reports, feature ideas | GitHub Issues | — |
| Architecture/scoring proposals | RFC PR in `docs/rfcs/` | CC BY 4.0 |

## 2. Development setup

Prerequisites: Docker + Docker Compose (v2), Git. That's all — **no API keys
are required** for any core feature (charter §6).

```bash
git clone https://github.com/fablepool/kite-map.git
cd kite-map
docker compose up --build
```

- Web client: http://localhost:5173
- API + interactive docs: http://localhost:8000/docs
- Postgres (PostGIS): localhost:5432, credentials in `.env.example`

The first run applies `db/schema.sql` and loads `data/seeds/` automatically.
For non-Docker workflows, see the per-package READMEs once the implementation
milestones land (`api/README.md`, `web/README.md`).

## 3. Branching and workflow

- `main` is always deployable; protected, PR-only, requires green CI + 1 review
  (2 reviews for changes to the scoring engine or public API).
- Branch names: `feat/<short-topic>`, `fix/<issue-number>-<topic>`,
  `docs/<topic>`, `rfc/<topic>`.
- Keep PRs focused. If a PR exceeds ~600 changed lines of non-generated code,
  expect a request to split it.
- Rebase on `main` before requesting review; we merge with squash by default.

## 4. Commit messages

We use [Conventional Commits](https://www.conventionalcommits.org/):

```
feat(scoring): apply gust-ratio penalty below 8 kn mean wind
fix(api): return 422 instead of 500 for out-of-range bbox
docs(rubric): clarify foil-kite low-wind band
data(spots): add 12 verified spots for the Dutch coast
```

Allowed types: `feat`, `fix`, `docs`, `data`, `refactor`, `test`, `perf`,
`build`, `ci`, `chore`. Scope is optional but encouraged
(`scoring`, `api`, `web`, `map`, `db`, `infra`).

Breaking changes to the public API must include a `BREAKING CHANGE:` footer
and follow the API versioning policy in `docs/07-api-contract.md` §2.

## 5. Code standards

### Backend (Python / FastAPI)
- Formatting and linting: `ruff format` + `ruff check` (config in
  `pyproject.toml`); type checking with `mypy --strict` on `app/scoring/` and
  `app/providers/`, standard elsewhere.
- All provider integrations go through the adapter interfaces in
  `docs/08-architecture.md` §4 — never call Open-Meteo/NOAA/Overpass directly
  from route handlers.
- Tests with `pytest`; external HTTP is **always** mocked or replayed from
  recorded fixtures (`tests/fixtures/`). CI has no network secrets and never
  will (charter §6.2).

### Frontend (TypeScript / React)
- `eslint` + `prettier`, strict TypeScript (`"strict": true`).
- Map interactions live in the map adapter layer so Leaflet/MapLibre remain
  swappable (`docs/04-data-sources.md` §2.4).
- Component tests with Vitest + Testing Library; the flyability badge and
  wind-arrow components require accessibility tests (labels, contrast tokens).

### The scoring engine (special rules)
The flyability score is safety-relevant. Therefore:
- Every change to `app/scoring/` must update or add table-driven test cases
  mapping rubric rows in `docs/05-flyability-scoring.md` to expected scores.
- Semantics changes (band edges, penalty weights, new factors) require an RFC
  (charter §4.2) and a rubric doc update **in the same PR**.
- The rubric doc is the source of truth; if doc and code disagree, that is a
  release-blocking bug.

## 6. Spot data contributions

Spots can be submitted in-app (preferred, goes through the moderation queue)
or via PRs to `data/seeds/*.geojson` for bulk regional additions.

Requirements for a spot record (see `docs/06-database-schema.md` for fields):
- Coordinates of the **launch area**, not the parking lot (add parking as a
  separate POI field).
- At least one hazard assessment: power lines, trees, airports/airfields
  within 5 km (check your national aviation rules), crowds, water hazards.
- `suitable_for` flags must be honest: do not mark a spot kite-surfable unless
  it has a documented rideable water area and launch zone.
- Sources: personal knowledge (state it), club websites (link them), or OSM
  (ODbL-compatible by design). **Never** copy from proprietary spot guides,
  Google Maps reviews, or paid apps — these are license violations and will be
  reverted.

Spot moderators review submissions per `docs/02-feature-spec.md` §F-07.
Disagreements escalate to maintainers; safety-conservative edits win ties.

## 7. Sign-off (DCO)

We do not use a CLA. Instead, every commit must be signed off:

```bash
git commit -s -m "feat(scoring): ..."
```

The `Signed-off-by: Your Name <you@example.com>` line certifies the
[Developer Certificate of Origin v1.1](https://developercertificate.org/):
that you wrote the contribution or otherwise have the right to submit it under
the project's licenses (MIT for code, CC BY 4.0 for docs, ODbL for data).
CI rejects unsigned commits. Pseudonyms are fine; a reachable email is required.

## 8. Pull request checklist

Before requesting review:

- [ ] CI green locally: `make check` (lint, types, tests for touched packages)
- [ ] New behavior covered by tests; scoring changes covered by rubric-mapped tests
- [ ] Docs updated (API changes → `api/openapi.yaml` + `docs/07-api-contract.md`;
      schema changes → `db/schema.sql` + a migration + `docs/06-database-schema.md`)
- [ ] No new external service calls outside the provider adapter layer
- [ ] No new dependency requiring payment or an API key for core features
- [ ] All commits signed off (`git commit -s`)
- [ ] Attribution requirements preserved (OSM/Open-Meteo notices intact)

## 9. Issue labels and getting started

- `good first issue` — scoped, mentored, with pointers to relevant docs.
- `help wanted` — maintainers want this but can't prioritize it.
- `rfc` — needs design discussion before code.
- `data` — spot database and moderation work.
- `funded` — carries a bounty from the public ledger (charter §8).

Unsure where to start? Open a draft PR early or ask in the issue — we'd rather
redirect ten minutes of work than ten hours.

## 10. Review SLAs and merging

- First maintainer/committer response on PRs: target 5 calendar days.
- Stale PRs (no author response for 30 days after review) are closed politely
  and can be reopened anytime.
- Merging uses lazy consensus per the charter; any maintainer veto comes with
  a written rationale you can respond to or escalate.

## 11. Security issues

Do **not** open public issues for vulnerabilities. Email the security contact
listed in `SECURITY.md` (until that file lands: the address in the repository
description). See charter §4.5 for response targets and disclosure policy.