Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
132 lines (103 loc) · 6.82 KB

CONTRIBUTING.md

File metadata and controls

132 lines (103 loc) · 6.82 KB
Raw

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

  8. 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!

Documentation versions

Publishing a release also deploys the documentation, versioned with mike on the gh-pages branch:

  • A stable release deploys its docs under XX.YY/ and moves the latest alias (the version the site root redirects to) to it.
  • A pre-release (e.g. vXX.YY.0-rc.1) deploys under a rolling rc/ version (titled with the full tag) and leaves latest untouched, so the public default stays on the latest stable release.
  • Every push to main refreshes the dev version.

Docs for any version can be (re)deployed manually from the docs workflow via "Run workflow": run it on main (dispatch uses the workflow definition at the selected ref, and tags predating it have no manual trigger), put the git tag to build from in the "ref" input, set the docs version (e.g. 0.3), and tick "latest" only if the site root should point there.

When undoing a bad release (see below), note that deleting the release and tag does not undo its docs deployment. To roll the docs back:

  1. If the bad version should disappear entirely, delete it from gh-pages with the same pinned mike fork the workflow uses (the mike on PyPI is not Zensical-compatible):

    uvx --from "git+https://github.com/squidfunk/mike.git@2d4ad799442f4592db8ad53b179bfb33db8c69ac" \
  --with "mkdocstrings[python]" mike delete --push XX.YY

  2. Re-run the docs workflow on main with "ref" set to the last good tag, its docs version, and "latest" ticked. Pages only updates through the workflow — never from gh-pages pushes alone — so this single run moves the public default back and republishes the site without the deleted version.

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