Skip to content

Latest commit

 

History

History
259 lines (170 loc) · 6.66 KB

CONTRIBUTING.md

File metadata and controls

259 lines (170 loc) · 6.66 KB

Contributing to PyHamcrest

Thank you for your interest in contributing to PyHamcrest! This guide will help you get started.

Table of Contents

Development Setup

Prerequisites

Installation

  1. Fork and clone the repository:
git clone https://github.com/YOUR-USERNAME/PyHamcrest.git
cd PyHamcrest
  1. Install pre-commit hooks:
prek install

This ensures code style checks run automatically before each commit.

(Optional) use a virtualenv

With uv installed, prefixing all commands with uv run ensures they run with the project dependencies. If you want to work in a virtualenv, so that you can run bare commands, you can do so this way:

uv sync
. .venv/bin/activate

In all instructions below, you can remove the uv run and uv tool run prefixes.

Running Tests

Quick Test Run

Run tests with pytest:

uv run pytest

Run a specific test file:

uv run pytest tests/hamcrest_unit_test/core/isequal_test.py

Run a specific test:

uv run pytest tests/hamcrest_unit_test/core/isequal_test.py::TestClass::test_name

Test Coverage

Run tests with coverage:

uv run coverage run -m pytest
uv run coverage report

Testing Across Python Versions

We use tox to test across multiple Python versions:

# Test all available Python versions (skips missing interpreters)
uv tool run tox -s

# Test specific Python version
uv tool run tox -e py312

# Test with numpy support
uv tool run tox -e py312-numpy

IMPORTANT: Always run uv tool run tox -s before submitting a pull request to verify tests pass across all available Python versions. The -s flag skips missing interpreters.

Supported Python Versions

  • Python 3.10, 3.11, 3.12, 3.13, 3.14
  • PyPy 3.11

Code Style and Linting

PyHamcrest uses automated code formatting and linting:

Auto-formatting

Code is formatted with Black and Ruff.

Run pre-commit hooks on all files:

prek run --all-files

Or via tox:

uv tool run tox -e lint

Style Notes

  • Line length: 100 characters
  • The codebase intentionally uses star imports (from module import *) to provide a clean public API
  • Import order is managed by isort with a custom "hamcrests" profile

Type Checking

PyHamcrest includes type annotations and is checked with mypy.

Run type checking:

uv run mypy src/

Or via tox:

uv tool run tox -e typing

Type Hint Tests

Type hints are tested using mypy with special test files in tests/type-hinting/. These files use a YAML format to test that type annotations work correctly. If you're adding or modifying type annotations, consider adding corresponding type tests.

Adding Changelog Entries

REQUIRED: Every pull request that changes functionality must include a changelog entry.

Exception: Documentation-only changes (README, CONTRIBUTING, etc.) do not require changelog entries.

PyHamcrest uses towncrier to manage the changelog.

How to Add a Changelog Entry

For every PR that changes code or functionality, create a changelog fragment file in the changelog.d/ directory:

Format: changelog.d/{issue_or_pr_number}.{category}.rst

Categories:

  • feature - New features or enhancements
  • bugfix - Bug fixes
  • misc - Miscellaneous changes (CI, docs, refactoring, etc.)

Example: If your PR is #123 and adds a new feature, create:

changelog.d/123.feature.rst:

Add support for matching custom objects with has_attributes matcher.

Tips:

  • Keep descriptions concise and user-focused
  • Write in the past tense ("Added", "Fixed", not "Add", "Fix")
  • Don't include implementation details unless relevant to users
  • The issue/PR number in the filename will be automatically linked in the generated changelog

Submitting Pull Requests

Before Submitting

  1. ✅ Run tests: uv tool run tox -s
  2. ✅ Run linting: prek run --all-files
  3. ✅ Run type checking: uv tool run tox -e typing
  4. ✅ Add changelog entry (REQUIRED for code changes) - see Adding Changelog Entries
  5. ✅ Update documentation if needed

CI Checks

When you create a pull request, GitHub Actions will automatically run:

  • Tests on Python 3.10, 3.11, 3.12, 3.13, 3.14, and PyPy 3.11
  • Tests on Linux, macOS, and Windows
  • Linting checks
  • Type checking
  • Documentation build

The CI workflow runs on:

  • All pull requests to main or master
  • Pushes to main, master, or branches starting with ci-testing-*

PR Guidelines

  • Branch naming: Use descriptive names like fix-issue-123 or add-new-matcher
  • Commit messages: Write clear, descriptive commit messages
  • PR description: Explain what changes you made and why
  • Link issues: Reference related issues in your PR description (e.g., "Fixes #123")
  • Keep PRs focused: One feature or fix per PR makes review easier

Release Process (for Maintainers)

PyHamcrest uses automated releases via git tags.

Creating a Release

  1. Ensure all PRs for the release are merged to main

  2. Run the release script:

./release.sh V2.2.0

This script:

  • Creates a git tag (e.g., V2.2.0)
  • Runs uv run towncrier build to generate the changelog from fragments in changelog.d/
  • Re-tags to include the changelog changes
  • Prompts you to push the tag
  1. Push the tag to trigger the release:
git push origin --tags "V2.2.0"
  1. GitHub Actions automatically:
  • Builds the package (wheel and sdist)
  • Publishes to PyPI using trusted publishing
  • Creates a GitHub release

Versioning

  • Format: V{major}.{minor}.{patch} (e.g., V2.1.0)
  • Version is automatically derived from git tags using hatch-vcs
  • No manual version bumping needed in code

Questions?

If you have questions or need help:

Thank you for contributing! 🎉