notion-sql/CONTRIBUTING.md

Contributing

Development Setup

Install the Rust toolchain and the release tooling listed in README.md.

Useful local checks:

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test
cargo build --release

Local development gates

This repo enforces formatting, linting, documentation, license headers, and supply-chain policy. To run the same checks locally:

• One-time setup (installs the git hooks): just setup (or git config core.hooksPath .githooks)
• Fast gate (runs automatically on commit): just check — cargo fmt --check, cargo clippy --all-targets --all-features -- -D warnings, ./scripts/check-headers.sh
• Full gate (run before pushing): just test, just deny, just doc

Tooling required: rustfmt + clippy (rustup components), and for the full gate cargo install cargo-deny. just is optional — the hook and CI call cargo directly.

Every .rs file must begin with:

// SPDX-License-Identifier: MIT
// Copyright (c) 2026 James Maes

All public and private items must carry doc comments — missing_docs and clippy::missing_docs_in_private_items are denied (they fail the build, not just CI).

Branches

Use feature/* branches for pull requests into develop.

Release candidates stabilize on release/* or rc/* branches. Production releases are tagged from main.

Pull Requests

Pull requests should include:

• A short description of the change.
• Tests for parser, filter, or value-coercion behavior when those paths change.
• Notes about Notion API behavior if the change affects API payloads.

Mutating Notion behavior should stay dry-run by default unless the user explicitly passes --apply.