Contributing

Concise guide to get a change from idea to merged.

1. Setup

Prerequisites:

• Python 3.12+
• uv (see: https://docs.astral.sh/uv/getting-started/installation/)

git clone https://github.com/yourusername/notionary.git cd notionary uv sync --all-extras uv run pre-commit install uv run pytest # sanity check 

2. Workflow

git checkout -b feature/short-description  # implement uv run pytest # tests uv run ruff check . # lint uv run ruff format . # format (or let pre-commit do it) uv run mypy notionary # types  git add . git commit -m "feat: short description" git push origin feature/short-description 

Open a Pull Request (PR) when the change is isolated and passes local checks.

3. Local Checks

Tool	Purpose
Ruff	Lint + format
Pytest	Tests
MyPy	Type safety
pre-commit	Runs the above fast before each commit

You normally only run pytest explicitly; the rest is enforced automatically.

4. Contribution Areas

• Bug fixes
• Small quality improvements (naming, clarity, docs)
• Documentation & examples
• Additional tests (round‑trip, regression, fixtures)
• Features you would like to see in Notionary

5. Style & Scope

• Keep PRs small and focused; large refactors → split.
• Avoid drive‑by formatting unrelated to the change.
• Public API changes must be documented and mentioned in the PR description.
• Prefer incremental improvement over speculative abstraction.