Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
125 lines (88 loc) · 4.87 KB

CONTRIBUTING.md

File metadata and controls

125 lines (88 loc) · 4.87 KB
Raw

Contributing

Thanks for helping improve SQLBuild. Keep changes focused, tested, and easy to review.

Setup

SQLBuild supports Python 3.12, 3.13 and 3.14.

Install dependencies with:

uv sync --python 3.12 --all-extras

Development Workflow

  • Create a branch for your change.
  • Keep pull requests focused on one behavior change or cleanup.
  • Add or update tests for behavior changes.
  • Prefer small, direct changes over broad rewrites.
  • Do not commit secrets, credentials, machine-local config, or generated scratch files.

Checks

Native development loop

After installing dependencies, rebuild the Python extension after Rust edits with:

make dev-native
uv run --no-sync pytest tests/integration/src/sqlbuild/compiler/compiled_project/test_native_resource_diagnostics.py -n auto --dist loadfile

Choose the test file covering your change. dev-native builds the extension in place with Maturin's development profile and skips wheel installation and dependency resolution. Use uv run --no-sync for subsequent focused checks so the package manager does not replace that extension with a release build. Python-only source edits need no native rebuild.

For a change confined to one Rust crate, run its focused tests before rebuilding the extension:

cargo test -p sqlbuild-sqltext given_model_files_when_matching_headers_then_offsets_follow_the_python_pattern

Keep the toolchain, CARGO_TARGET_DIR, profile and RUSTFLAGS consistent between iterations. Changing them can invalidate compiled artifacts. Coordinate builds that share a target directory; do not delete another task's artifacts or change global compiler-cache settings. The first build for a new profile is a setup cost, not an incremental-build measurement.

The development profile keeps workspace crates unoptimised with line-table debug information; dependencies use light optimisation without debug information. This trades development runtime speed for faster changes to our code while avoiding fully unoptimised dependency execution.

Development builds are for correctness iteration. Before measuring compiler performance, restore the production profile and run measurements without concurrent builds:

uv run --no-sync maturin develop --release --skip-install

Do not compare development-profile timings with release benchmarks. Dependency or packaging changes still require uv sync --all-extras; --skip-install does not refresh installed metadata, dependencies or console scripts.

Always pass --skip-install to maturin develop, or use make dev-native or make fast-native. Without it, maturin installs the sqlbuild-cli version that pyproject.toml pins from the package index, not this checkout's crates/sqlbuild-cli: the sqb executable is then a released build, and between a release commit and its publication the install fails because that version does not exist yet. uv sync and uv run install the workspace sqlbuild-cli and rebuild the extension when Rust sources change.

Before opening a pull request, run:

make check

For broader validation, run:

make verify

For focused iteration, run the narrowest relevant pytest target, for example:

pytest tests/unit/src/sqlbuild/compiler/compile/test_main.py

To check whether a branch introduces copied or drifting code in Python or Rust, run:

uv run fensu dupes --since origin/main

make dupes reports the whole repository. The report is advisory and never needs to reach zero; [dupes] in fensu.toml configures exclusions and contract exemptions. See fensu dupes --help.

Tests

  • Mirror source layout under tests/<scope>/src/sqlbuild/....
  • Prefer dataclass-backed test cases for non-trivial scenarios.
  • Use clear Given-When-Then test names.
  • Prefer real parsing, filesystem, compile, and planner behavior over mocks when practical.
  • For substantive behavior changes, validate test strength with a small semantic mutation and confirm the relevant test fails before reverting it.

Project Conventions

  • Keep sqb compile offline and static unless intentionally changing that contract.
  • Keep examples reproducible and avoid environment-specific assumptions.
  • Use project-local config files for local overrides, and do not commit credentials or personal settings.
  • Follow existing code style and module organization before introducing new patterns.

Commits And Pull Requests

  • Use concise conventional commit messages, such as fix: ..., feat: ..., test: ..., or docs: ....
  • In pull requests, summarize the behavior change and list the checks you ran.
  • Call out breaking changes, migrations, or compatibility decisions explicitly.

Before creating or editing a pull request, write its description to a file and validate the current branch, proposed title, and description locally:

make check-pr-metadata PR_TITLE='type: concise summary' PR_BODY_FILE=/path/to/pr-body.md