Contributing to pyhs3

We welcome contributions to pyhs3! This guide will help you get started with contributing to the project.

See the Scientific Python Developer Guide for a detailed description of best practices for developing scientific packages.

Getting Started

Prerequisites

Before contributing, ensure you have:

  • Python 3.10 or higher

  • Git

  • A GitHub account

Quick Development

The fastest way to start with development is to use nox. If you don’t have nox, you can use pipx run nox to run it without installing, or pipx install nox. If you don’t have pipx (pip for applications), then you can install with pip install pipx (the only case where installing an application with regular pip is reasonable). If you use macOS, then pipx and nox are both in brew, use brew install pipx nox.

To use, run nox. This will lint and test using every installed version of Python on your system, skipping ones that are not installed. You can also run specific jobs:

$ nox -s lint  # Lint only
$ nox -s tests  # Python tests
$ nox -s docs -- --serve  # Build and serve the docs
$ nox -s build  # Make an SDist and wheel

Nox handles everything for you, including setting up a temporary virtual environment for each run.

Setting Up Your Development Environment Manually

  1. Fork and clone the repository

    git clone https://github.com/YOUR-USERNAME/pyhs3.git
cd pyhs3

  2. Create a development environment

    You can set up a development environment by running:

    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .[dev,test,docs]

    If you have the Python Launcher for Unix, you can instead do:

    py -m venv .venv
py -m install -e .[dev]

  3. Set up pre-commit hooks

    You should prepare pre-commit, which will help you by checking that commits pass required checks:

    pip install pre-commit  # or brew install pre-commit on macOS
pre-commit install  # Will install a pre-commit hook into the git repo

    You can also/alternatively run pre-commit run (changes only) or pre-commit run --all-files to check even without installing the hook.

Code Standards

Code Style

We follow strict code quality standards:

  • Formatting: We use ruff format for code formatting

  • Linting: We use ruff check for linting

  • Type checking: We use mypy for static type checking

  • Docstring style: We follow numpy-style docstrings checked with pydocstyle

All of these are enforced through pre-commit hooks.

Type Hints

All code must include type hints. We enforce this through mypy with strict settings:

from __future__ import annotations


def calculate_logpdf(x: float, mean: float, sigma: float) -> float:
    """Calculate log PDF of a Gaussian distribution."""
    ...

Testing

All contributions must include tests. See testing for detailed information on writing and running tests.

Quick testing commands:

pytest  # Run all tests
pytest --cov=pyhs3  # Run tests with coverage

Documentation

  • All public APIs must have docstrings

  • Update relevant documentation files when adding features

  • Use numpy-style docstrings

You can build the docs using:

nox -s docs

You can see a preview with:

nox -s docs -- --serve

Git Workflow

Branch Naming

Create descriptive branch names:

  • feat/feature-name for new features

  • fix/bug-description for bug fixes

  • docs/documentation-topic for documentation changes

  • refactor/refactoring-description for refactoring

Commit Messages

We use semantic commit messages:

  • feat: add new distribution type

  • fix: correct parameter ordering in histogram

  • docs: update contributing guide

  • test: add tests for composite distributions

  • refactor: simplify parameter validation

  • style: format code with ruff

  • chore: update dependencies

Commits should be:

  • Small and focused: Each commit should represent a single logical change

  • Well-described: Explain why the change was made, not just what changed

  • Frequent: Commit often to track your progress

Pull Request Process

  1. Create a WIP branch for your work if you don’t have an existing branch

  2. Make your changes following the code standards

  3. Write tests for your changes

  4. Run the test suite to ensure everything passes:

    nox -s tests

  5. Run linting to check code quality:

    pre-commit run --all-files

  6. Update documentation if needed

  7. Commit your changes with semantic commit messages

  8. Push to your fork and create a pull request

  9. Respond to review feedback promptly

Pull Request Guidelines

  • Provide a clear description of what your PR does

  • Reference any related issues

  • Include examples or use cases if applicable

  • Ensure CI passes before requesting review

  • Keep PRs focused on a single feature or fix

Code Review

  • Be patient and respectful during code review

  • Address all review comments

  • Push back with technical reasoning if you disagree

  • Don’t take criticism personally - we’re all learning

Where to Get Help

If you need help:

  • Open a discussion for questions

  • Check existing issues for similar problems

  • Read the development guide for detailed workflow information

  • Review the architecture guide to understand the codebase structure

Community Guidelines

Please read and follow our Code of Conduct. We are committed to providing a welcoming and inclusive environment for all contributors.

Additional Resources