Skip to content

Contributing Guide

Where to start?

Please check out the issues tab. Let's have a discussion over there before proceeding with any changes. Great minds think alike -- someone may have already created an issue related to your inquiry. If there's a bug, please let us know.

If you're totally new to open source development, I recommend reading Xarray's contributing guide.

Developer setup

We use uv to manage the project. This project also contains a Rust extension (built with maturin), so a Rust toolchain is required.

  1. Install Rust: https://rustup.rs/
  2. Install uv: https://docs.astral.sh/uv/getting-started/installation/
  3. Clone the repository (bonus: via SSH) and cd xarray-sql (the project root).
  4. Install Python dev dependencies (without building the Rust extension yet): 
    uv sync --dev --no-install-package xarray-sql
  5. Build and install the Rust extension into the virtual environment: 
    uv run --no-project maturin develop --uv
    This compiles the native code and links it so that import xarray_sql works. Re-run this step whenever you modify any Rust source files under src/.
  6. Run the test suite to verify your setup: 
    uv run --no-project pytest -v . -m "not integration"
  7. Install pre-commit hooks: uvx pre-commit install

This will automatically run code formatting and type checking before each commit. You can also run the hooks manually with: uvx pre-commit run --all-files 7. Build and serve docs locally: uvx zensical serve

Before submitting a pull request...

Thanks so much for your contribution! For a volunteer led project, we so appreciate your help. A few things to keep in mind:

  • Please be nice. We assume good intent from you, and we ask you to do the same for us.
  • Development in this project will be slow if not sporadic. Reviews will come as time allows.
  • Every contribution, big or small, matters and deserves credit.

Here are a few requests for your development process:

  • We require all code to be formatted with pyink and type-checked with mypy. These checks run automatically via pre-commit hooks (see Developer setup above). If you need to run them manually:
  • Formatting: uvx pre-commit run pyink --all-files or uvx pyink .
  • Type checking: uvx pre-commit run mypy --all-files or uvx mypy xarray_sql/
  • Please include unit tests, if possible, and performance tests when you touch the core functionality (see perf_tests/).
  • It's polite to do a self review before asking for one from a maintainer. Don't stress if you forget; we all do sometimes.
  • Please add (or update) documentation when adding new code. We use Google Style docstrings.
  • We are thrilled to get documentation-only PRs -- especially spelling and typo fixes (I am a bad speller). If writing tutorials excites you, it would be to everyone's benefit.

Versioning Guidelines

We're using an "experimenter's" SemVer: We're figuring out what a solid API should be, working towards finality and stability in the 1.0.0 release. Until then, new features will be introduced under the minor version (XX.MINOR.ZZ), and incremental (non-API surface) changes will live under the patch version (XX.YY.PATCH).

Releasing

To create a release, please do the following:

  1. Increment the version in the Cargo.toml file manually to whatever the next release will be. This needs to be merged. You can make a PR, but I often just make a quick push to main.
  2. Git tag the release version: git tag -a vXX.YY.ZZ -m 'Headline description goes here'.
  3. Push the release to the remote: git push origin vXX.YY.ZZ
  4. In the GitHub, go to the Releases page. Please click "Draft new release."
  5. On that page, select the tag that you just pushed. Add a title that follows the pattern of all other releases: (Something like: vXX.YY.ZZ: Headline description goes here)
  6. Generate the release notes and maybe add a one line description to accompany it.
  7. Click "Publish Release". This will kick of a GitHub action to build the project and push the binaries + wheels to PyPI.
  8. Celebrate a successful release!

Undoing a bad release

We all mess up sometimes. For example, I have often forgotten to do one of the steps (often, step 1) in the above process, and it leads to a failed release (i.e. an unsuccessful push to PyPI.) To recover from this, please do the following and then try the above steps again:

  1. Go to the Releases page. Click into the release that didn't go so well.
  2. Click the red delete button (a trash can).
  3. Delete the tag in the remote: git push --delete origin vXX.YY.ZZ
  4. Delete your tag locally with git tag -d vXX.YY.ZZ