Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
119 lines (80 loc) · 2.38 KB

CONTRIBUTING.md

File metadata and controls

119 lines (80 loc) · 2.38 KB
Raw

Contributing to numpy-stl

Contributions are welcome! This guide covers the modern development workflow.

Quick Start

  1. Clone and install:

    git clone https://github.com/WoLpH/numpy-stl.git
cd numpy-stl
uv sync --all-extras

  2. Install git hooks:

    lefthook install

  3. Run tests:

    uv run pytest

  4. Lint and format:

    ruff check stl tests
ruff format stl tests

  5. Type check:

    ty check

Development Workflow

Prerequisites

  • Python 3.10+
  • uv (package manager)
  • lefthook (git hooks)

Running the Full Test Suite

uv run pytest

This runs all tests with coverage reporting and doctest validation.

To run a subset:

uv run pytest tests/test_mesh.py -x

Pre-commit Hooks

Lefthook runs these checks in parallel on every commit:

  • ruff check -- linting
  • ruff format -- code formatting (auto-fixes staged)
  • ty check -- type checking

If a hook fails, fix the issue and re-commit.

Code Style

  • Formatter: ruff (79-character line length)
  • Quotes: single quotes for all strings, including docstrings
  • Docstrings: Google-style (Args:, Returns:, Raises:)
  • Type hints: required on all functions and methods

Building Documentation

uv sync --extra docs
cd docs
uv run sphinx-build -b html . _build/html

Open docs/_build/html/index.html to preview.

Pull Request Guidelines

  1. The PR should include tests for new functionality
  2. All CI checks must pass (tests, lint, type checking)
  3. The PR should work for Python 3.10, 3.11, 3.12, and 3.13

Reporting Bugs

File issues at https://github.com/WoLpH/numpy-stl/issues.

Include:

  • Your OS and Python version
  • Steps to reproduce
  • Expected vs actual behavior
  • If applicable, the STL file that triggers the issue

Automatic formatting

Pull requests apply Ruff fixes before the lint check. With the autofix.ci app installed for this repository, those fixes are committed to the pull request branch, including forks. Findings Ruff cannot fix still fail CI. The CI lint job checks committed files on pushes. The separate autofix.ci workflow also runs on pushes to develop and master and can commit fixes.

Apply the same fixes locally with:

uvx --with tox-uv tox -e ruff-fix