Contributing to PyStrata

We welcome contributions to PyStrata! This guide will help you get started with contributing code, documentation, or examples.

Development Setup

Prerequisites

  • Python 3.8 or higher

  • Git for version control

  • UV for dependency management

Getting Started

  1. Fork the repository on GitHub

  2. Clone your fork locally:

    git clone https://github.com/yourusername/pystrata.git
cd pystrata

  3. Set up the development environment:

    uv sync
uv run pre-commit install

  4. Create a feature branch:

    git checkout -b feature-name

Development Workflow

Environment Management

PyStrata uses UV for fast dependency resolution and environment management:

# Install all dependencies including dev tools
uv sync

# Run tests
uv run pytest

# Run linting
uv run ruff check src/ tests/
uv run ruff format src/ tests/

# Run type checking
uv run mypy src/

Code Quality Tools

We use several tools to maintain code quality:

  • Ruff - Fast Python linter and formatter

  • MyPy - Static type checking

  • pytest - Testing framework

  • pre-commit - Git hooks for automated checks

Testing

Run the test suite to ensure your changes don’t break existing functionality:

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=pystrata

# Run specific test file
uv run pytest tests/test_motion.py

Contributing Guidelines

Code Style

  • Follow PEP 8 style guidelines

  • Use descriptive variable and function names

  • Add type hints to all public functions

  • Maximum line length of 88 characters (Black default)

Documentation

  • All public functions must have docstrings in NumPy format

  • Include examples in docstrings where helpful

  • Update relevant documentation files for new features

  • Add references to scientific literature where appropriate

Testing

  • Write tests for all new functionality

  • Aim for high test coverage (>90%)

  • Use descriptive test names

  • Include edge cases and error conditions

Commit Messages

Use clear, descriptive commit messages:

Add support for frequency-dependent damping in RVT motions

- Implement FDDampingMixin class
- Add tests for frequency-dependent behavior
- Update documentation with new damping options

Closes #123

Types of Contributions

Bug Fixes

  • Check existing issues before starting

  • Include a test that reproduces the bug

  • Provide clear description of the fix

New Features

  • Discuss major features in an issue first

  • Ensure backward compatibility when possible

  • Add comprehensive tests and documentation

  • Follow existing patterns and conventions

Documentation

  • Fix typos and improve clarity

  • Add examples and tutorials

  • Expand API documentation

  • Improve mathematical explanations

Examples

  • Create realistic analysis scenarios

  • Include clear explanations and context

  • Test all code in examples

  • Provide appropriate data files

Pull Request Process

  1. Before submitting:

    • Ensure all tests pass

    • Run the linting tools

    • Update documentation as needed

    • Add appropriate test coverage

  2. Creating the PR:

    • Use a descriptive title

    • Reference any related issues

    • Provide clear description of changes

    • Include any breaking changes in the description

  3. Review process:

    • Respond to reviewer feedback promptly

    • Make requested changes in new commits

    • Keep the PR focused and reasonably sized

Code Organization

PyStrata follows a modular architecture:

Core Modules

  • pystrata.motion - Input ground motion handling

  • pystrata.site - Site profile and layer definitions

  • pystrata.propagation - Wave propagation calculators

  • pystrata.output - Output quantity computation

  • pystrata.variation - Parameter variation and uncertainty

Design Principles

  • Composition over inheritance - Use mixins and composition

  • Immutable objects - Prefer immutable data structures

  • Clear interfaces - Well-defined public APIs

  • Minimal dependencies - Keep the core lightweight

Release Process

PyStrata uses semantic versioning (MAJOR.MINOR.PATCH):

  • MAJOR - Incompatible API changes

  • MINOR - New functionality (backward compatible)

  • PATCH - Bug fixes (backward compatible)

Releases are automated using GitHub Actions and triggered by version tags.

Getting Help

  • GitHub Issues - Bug reports and feature requests

  • GitHub Discussions - Questions and general discussion

  • Documentation - Comprehensive guides and API reference

Community Guidelines

We are committed to providing a welcoming and inclusive environment:

  • Be respectful and constructive

  • Focus on the technical merits

  • Help newcomers get started

  • Follow the code of conduct

Thank you for contributing to PyStrata!