Contributing to tylertoo¶

Contributors agree to follow the Code of Conduct. Report security issues privately through SECURITY.md.

For bugs and feature requests, use the issue templates.

Issue priorities¶

Every open issue carries a priority label, P0 (most urgent) to P3, and a kind label: bug, optimization, or enhancement. AGENTS.md defines the scale. When you report a bug, fill in the template's Impact and Workaround fields, and a maintainer assigns the labels.

Development setup¶

git clone https://github.com/geoparquet-io/tylertoo.git
cd tylertoo
git config core.hooksPath .githooks
cargo build

DEVELOPMENT.md covers setup, daily development, and local CI checks.

Commit convention¶

Commit messages follow Conventional Commits:

Pull request process¶

1. Branch from main. Branch protection rejects direct pushes.
2. Run CI checks locally. At minimum, run cargo fmt --all --check, cargo clippy, cargo shear, and targeted tests, plus the uv run suite for Python changes. CI requires these checks to pass. DEVELOPMENT.md → CI gates lists every gate with its command.
3. Open the PR with the PR template. Never bypass the pre-commit hook with --no-verify.

The diff-scoped mutation check is advisory. Its job summary and sticky PR comment list mutants in your change that tests missed. Use these to find test gaps. Run scripts/mutants-diff.sh to reproduce the check locally.

Docstrings and help text¶

For public docstrings, CLI help, and /// docs:

• Open with a one-line summary that ends with a period.
• Describe what each parameter does for the user in at most two sentences.
• Leave out issue numbers, references to sweeps or decision files, restated defaults, internal crate names, memory formulas, and tuning history.
• Give a performance-only knob one sentence and a link to the scaling guide. Put tippecanoe comparisons in the tippecanoe guide.
• Keep one short runnable example per function. Move removed material users still need to docs/OVERVIEW_TUNING.md, a guide, or CHANGELOG.md.

Releasing (maintainers)¶

Prerequisites¶

1. Install Commitizen: uv tool install commitizen.
2. Set the GitHub secret CARGO_REGISTRY_TOKEN from crates.io/settings/tokens.
3. Configure PyPI trusted publishing.

Release workflow¶

1. Branch from an up-to-date main:

git checkout main
git pull
git checkout -b release/vX.Y.Z

1. Bump the version from the repo root, never from crates/python. Choose MINOR, PATCH, or MAJOR. Delete Commitizen's local tag so the workflow can tag the merged commit:

uv run cz bump --increment MINOR --changelog
git tag -d vX.Y.Z

1. Check the build:

cargo check

1. Curate CHANGELOG.md (see below) and commit it.
2. Push the branch and open the PR:

git push -u origin release/vX.Y.Z
gh pr create --title "Release vX.Y.Z" \
  --body "Release vX.Y.Z"

1. After the merge, start the release from main:

gh workflow run release.yml --ref main

release.yml reads the version from Cargo.toml on main, tags that commit vX.Y.Z, publishes to crates.io and PyPI, and creates a GitHub release with prebuilt CLI binaries.

A manual run tags the latest commit on main. If other PRs merged after the release PR, tag the release PR's merge commit directly. Pushing the tag starts the same workflow:

git fetch origin
git tag vX.Y.Z <merge-commit>
git push origin vX.Y.Z

Before building, the workflow stops the release if:

• the commit is not on main
• a pushed tag does not match the Cargo.toml version
• the run started on any ref other than main or the vX.Y.Z tag
• the vX.Y.Z tag already exists on a different commit

Curating the changelog¶

cz bump --changelog generates entries from commits. Before releasing, edit the new section of CHANGELOG.md for users:

• Group the entries under Added, Changed, Fixed, and Performance.
• Give each user-visible change one line with its PR reference.
• Combine clippy, fmt, CI, dependency bumps, and other maintenance into one "Internal" line.
• Leave older sections alone.

docs/changelog.md links to CHANGELOG.md; the docs site uses the same file.

What Commitizen updates¶

The root .cz.toml defines Commitizen's config and version_files. A bump updates:

Commitizen leaves crates/python/uv.lock unchanged. The pre-commit hook runs uv lock and stages the updated project version. Keep the hook enabled when committing the bump. If the hook has not run, use cd crates/python && uv lock. The hook and the version check in the CI Lint job fail if the versions disagree.

Recovery¶

If the workflow fails after pushing the tag, fix the cause and rerun it on that tag. It detects the tag without a release, skips completed steps, and publishes the rest:

gh workflow run release.yml --ref vX.Y.Z

If the tag points at the wrong commit, delete it before you rerun:

git push origin :refs/tags/vX.Y.Z

Common issues¶