Contributing

We welcome contributions to pyhnhtools! This guide explains how to contribute code, documentation, and other improvements.

Code of Conduct

Please be respectful and constructive in all interactions. We are committed to providing a welcoming community for all contributors.

Getting Started

  1. Fork the Repository

    Visit https://github.com/YOUR-USERNAME/pyhnhtools and click “Fork”

  2. Clone Your Fork

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

  3. Add Upstream Remote

    git remote add upstream https://github.com/YOUR-USERNAME/pyhnhtools.git

  4. Create a Feature Branch

    git checkout -b feature/my-new-feature

  5. Install in Development Mode

    pip install -e ".[dev]"

Development Workflow

Code Style

Follow PEP 8:

pip install flake8
flake8 src/

Type Hints

Use type hints for all functions:

def load_input(filepath: str) -> ModelInput:
    """Load model from JSON file."""

Docstrings

Use Google-style docstrings:

def run_backwater(model: ModelInput, output_csv: Optional[str] = None) -> Results:
    """Run standard step 1D analysis.

    Args:
        model: Input model with geometry and parameters
        output_csv: Optional path to save results CSV

    Returns:
        Results object with water surface and velocity profiles

    Raises:
        ValueError: If model validation fails
    """

Testing

Write tests for new features:

pip install pytest pytest-cov
pytest tests/
pytest --cov=src/pyhnhtools tests/

Documentation

Update docs for public APIs:

cd docs
make html
# Open _build/html/index.html to preview

Submitting Changes

  1. Commit Your Changes

    git add .
git commit -m "Add feature: descriptive message"

  2. Push to Your Fork

    git push origin feature/my-new-feature

  3. Create Pull Request

    Visit your fork on GitHub and click “Compare & pull request”

  4. Write Clear PR Description

    • What does this PR do?

    • Why is it needed?

    • How was it tested?

    • Related issues?

  5. Respond to Feedback

    • Address review comments

    • Push additional commits

    • Maintain professional tone

PR Checklist

Before submitting, ensure:

  • [ ] Code follows PEP 8 style

  • [ ] Type hints are complete

  • [ ] Docstrings are comprehensive

  • [ ] Tests are included and passing

  • [ ] Documentation is updated

  • [ ] Commit messages are clear

  • [ ] No merge conflicts

Common Contributions

Bug Reports

Include:

  • Minimum reproducible example

  • Python version and OS

  • Full error traceback

  • Expected vs actual behavior

Feature Requests

Describe:

  • Problem it solves

  • Proposed API/interface

  • Use cases

  • Implementation ideas (optional)

Documentation

Improve:

  • Installation instructions

  • Usage examples

  • API reference

  • Tutorials and guides

Code Review

Help by:

  • Testing PRs locally

  • Providing constructive feedback

  • Suggesting improvements

  • Reviewing documentation

Setting Up Your Environment

Virtual Environment

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

Development Tools

pip install pytest black flake8 mypy sphinx

Pre-commit Hooks (optional)

pip install pre-commit
pre-commit install

Running Tests

Unit Tests

pytest tests/unit/

Integration Tests

pytest tests/integration/

All Tests with Coverage

pytest --cov=src/pyhnhtools --cov-report=html tests/

Specific Test

pytest tests/test_adapter.py::test_load_input

Building Documentation

cd docs
make clean html
python -m http.server -d _build/html 8000

Then open http://localhost:8000 in your browser.

Project Structure

pyhnhtools/
├── src/pyhnhtools/          # Main package code
├── tests/                   # Test files
├── docs/                    # Documentation
├── setup.py                 # Package configuration
├── CONTRIBUTING.md          # This file
├── LICENSE                  # License
└── README.md                # Project overview

Release Process

Maintainers use this process for releases:

  1. Update version in setup.py

  2. Update CHANGELOG.md

  3. Create git tag: git tag v0.2.0

  4. Push tag: git push upstream v0.2.0

  5. GitHub Actions builds and publishes to PyPI

  6. RTD builds documentation for new version

Licensing

By contributing, you agree your code is licensed under the project’s license (see LICENSE file).

Getting Help

  • Questions: Open an issue with label “question”

  • Bugs: Open an issue with label “bug”

  • Features: Open an issue with label “enhancement”

  • Discussions: Use GitHub Discussions tab

Thank You!

We appreciate all contributions, no matter how small. Every improvement helps make pyhnhtools better for everyone!