Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
222 lines (150 loc) · 5.6 KB

CONTRIBUTING.md

File metadata and controls

222 lines (150 loc) · 5.6 KB
Raw

Contributing to python-autopxd2

Contributions are welcome! This document covers development setup, code quality standards, and the release process.

Development Setup

We recommend using uv for fast dependency management.

  1. Clone the repository:

    git clone https://github.com/elijahr/python-autopxd2.git
cd python-autopxd2

  2. Create a virtual environment and install dependencies:

    # Using uv (recommended)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e '.[test,lint,docs]'

# Or using pip
python -m venv .venv
source .venv/bin/activate
pip install -e '.[test,lint,docs]'

  3. Install pre-commit hooks:

    pre-commit install

Code Quality

We use pre-commit with ruff for linting and formatting. The following checks run automatically on commit:

  • ruff - Linting (replaces flake8, pylint, isort, etc.)
  • ruff-format - Code formatting (replaces black)

To run all checks manually:

pre-commit run --all-files

Or run ruff directly:

ruff check autopxd       # Lint
ruff check --fix autopxd # Lint and auto-fix
ruff format autopxd      # Format

Type Checking

We use mypy with strict mode:

mypy autopxd/ --strict

Running Tests

pytest

Or with verbose output:

pytest -v

Real Header Tests

Some tests (test_real_headers.py) require actual C/C++ libraries to be installed. These tests are marked with @pytest.mark.real_headers.

Install test libraries:

# macOS
./scripts/install-test-libs-macos.sh

# Linux (Debian/Ubuntu)
sudo ./scripts/install-test-libs-linux.sh

Skip real header tests (if libraries aren't installed):

pytest -m "not real_headers"

Docker Development Environment

Build a Docker image with test libraries for running the full test suite:

docker build --build-arg TEST_MODE=1 -t autopxd2-test .
docker run --rm -v $(pwd):/app -w /app autopxd2-test pytest

Building Documentation

# Serve docs locally with live reload
uv run mkdocs serve

# Or without uv
mkdocs serve

# Build static site
mkdocs build

Submitting Changes

  1. Create a branch for your changes
  2. Ensure all tests pass and pre-commit checks are clean
  3. Submit a pull request with a clear description of the changes

Maintainer Guide

This section is for project maintainers who can publish releases.

Release Process

1. Prepare the Release

  1. Update version in pyproject.toml:

    version = "X.Y.Z"

  2. Update CHANGELOG.md with the release notes

  3. Commit and push to master:

    git add pyproject.toml CHANGELOG.md
git commit -m "Bump to vX.Y.Z"
git push origin master

Important: The git ref you release from (the tag, or the SHA passed to the manual workflow_dispatch) MUST contain the pyproject.toml version bump. workflow_dispatch accepts an arbitrary ref and will happily build and publish from a ref that lacks the bump.

Sdist completeness guard

The publish workflow builds the sdist and wheel, then runs check-manifest and twine check --strict before uploading the distribution artifacts. If the sdist is missing any version-controlled file that belongs in it (for example, a new test helper or fixture), check-manifest fails, the build job fails, and because publish-pypi depends on build, nothing is published.

check-manifest also runs locally via pre-commit, so drift is usually caught before you push. If it flags a new file, update MANIFEST.in (to ship it) or the [tool.check-manifest] ignore list in pyproject.toml (to keep it out of the sdist) — never weaken the gate to make it pass.

2. Create a GitHub Release

  1. Go to Releases
  2. Click Draft a new release
  3. Create a new tag: vX.Y.Z
  4. Set the release title: vX.Y.Z
  5. Add release notes (can copy from CHANGELOG.md)
  6. Click Publish release

This triggers the publish workflow automatically.

3. Approve the PyPI Deployment

The workflow uses a protected pypi environment that requires approval:

  1. Go to Actions
  2. Find the running "Publish to PyPI" workflow
  3. Click Review deployments
  4. Select the pypi environment and click Approve and deploy

The package will be published to PyPI via OIDC trusted publishing.

Manual Publishing (if needed)

You can also trigger a publish manually:

  1. Go to Actions → Publish to PyPI
  2. Click Run workflow
  3. Enter the git ref (tag or commit SHA)
  4. Click Run workflow
  5. Approve the deployment as above

PyPI Trusted Publishing Setup

This project uses PyPI Trusted Publishing (OIDC) instead of API tokens. This is configured on PyPI with:

  • Owner: elijahr
  • Repository: python-autopxd2
  • Workflow: publish.yml
  • Environment: pypi

To add a new maintainer who can approve deployments:

  1. Go to Settings → Environments → pypi
  2. Under Required reviewers, add the maintainer's GitHub username
  3. They must have write access to the repository

Verifying a Release

After publishing, verify:

  1. Package appears on PyPI
  2. Version is correct: pip index versions autopxd2
  3. Installation works: pip install autopxd2==X.Y.Z