Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
136 lines (88 loc) · 4.74 KB

CONTRIBUTING.md

File metadata and controls

136 lines (88 loc) · 4.74 KB
Raw

Development - Contributing

Issues and pull requests are more than welcome: https://github.com/developmentseed/titiler/issues

AI Use Policy

You may use AI tools to assist your contributions. You are fully responsible for everything you submit.

AI tools are part of modern development workflows and contributors may use them. However, all contributions must meet titiler quality standards regardless of how they were created.

Policy: We require a "human-in-the-loop." You are the author and are fully accountable for all submitted code. Please ensure all tool-generated content is thoroughly reviewed before submission to ensure it is not an "extractive contribution" that squanders maintainer time.

Ref: https://github.com/developmentseed/.github/blob/main/CODE_OF_CONDUCT.md

Guidelines

AI-assisted development is acceptable when used responsibly. Contributors must:

  • Test all code thoroughly. Submit only code you have verified works correctly.
  • Understand your contributions. You must be able to explain code you submit.
  • Write clear, concise PR descriptions in your own words.
  • Use your own voice in GitHub issues and PR discussions.
  • Take responsibility for code quality, correctness, and maintainability.

Note: Submitting AI-generated code with little thought behind it isn't much help. Maintainers have the same state-of-the-art models and can just generate a fix themselves, often faster than reviewing yours. Just create an issue instead.

Unacceptable Submissions

Pull requests and issues can be closed without review if they contain:

  • Untested code
  • Verbose AI-generated descriptions
  • Evidence the contributor doesn't understand the submission
  • Broken deployments or failing tests
  • Or even if the maintainers just suspect it being generated by AI and consider it adding noise instead of help

Using AI to assist learning and development is encouraged. Using it to bypass understanding or submit work you cannot explain is not.

Getting Help

Development Environment

We recommend using uv as project manager for development.

See https://docs.astral.sh/uv/getting-started/installation/ for installation

dev install

git clone https://github.com/developmentseed/titiler.git
cd titiler

# Install the package in editable mode, plus the "dev" dependency group.
# You can add `--group` arguments to add more groups, e.g. `--group notebook`.
uv sync

pre-commit

This repo is set to use pre-commit to run isort, ruff (linting and formatting), mypy, zizmor (GitHub Actions security audit), and commitizen (commit message linting) when committing new code.

uv run pre-commit install

# If needed, you can run pre-commit script manually
uv run pre-commit run --all-files

Conventional Commits

This repo enforces Conventional Commits. Commit messages must follow the format:

<type>[optional scope]: <description>

Common types: feat, fix, docs, chore, refactor, test, ci.

The commitizen pre-commit hook (installed in the commit-msg stage via uv run pre-commit install) validates each commit message locally. The same check runs in CI via the Commitlint GitHub Actions workflow on every push.

Release notes and version bumps are generated automatically from conventional commit history using Release Please.

Run tests

Each titiler's modules has its own test suite which can be ran independently

# titiler.core
uv run pytest src/titiler/core --cov=titiler.core -cov-report=term-missing

# titiler.extensions
uv run pytest src/titiler/extensions --cov=titiler.extensions --cov-report=term-missing

# titiler.mosaic
uv run pytest src/titiler/mosaic --cov=titiler.mosaic --cov-report=term-missing

# titiler.xarray
uv run pytest src/titiler/xarray --cov=titiler.xarray --cov-report=term-missing

# titiler.application
uv run pytest src/titiler/application --cov=titiler.application --cov-report=term-missing

or all at once:

./scripts/test

Docs

git clone https://github.com/developmentseed/titiler.git
cd titiler

# Build docs
uv run --group docs mkdocs build -f docs/mkdocs.yml

Hot-reloading docs:

uv run --group docs mkdocs serve -f docs/mkdocs.yml --livereload

To manually deploy docs (note you should never need to do this because Github Actions deploys automatically for new commits.):

uv run --group docs mkdocs gh-deploy -f docs/mkdocs.yml