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**

   .. code-block:: bash

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

3. **Add Upstream Remote**

   .. code-block:: bash

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

4. **Create a Feature Branch**

   .. code-block:: bash

      git checkout -b feature/my-new-feature

5. **Install in Development Mode**

   .. code-block:: bash

      pip install -e ".[dev]"

Development Workflow
--------------------

**Code Style**

Follow PEP 8:

.. code-block:: bash

   pip install flake8
   flake8 src/

**Type Hints**

Use type hints for all functions:

.. code-block:: python

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

**Docstrings**

Use Google-style docstrings:

.. code-block:: python

   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:

.. code-block:: bash

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

**Documentation**

Update docs for public APIs:

.. code-block:: bash

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

Submitting Changes
------------------

1. **Commit Your Changes**

   .. code-block:: bash

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

2. **Push to Your Fork**

   .. code-block:: bash

      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**

.. code-block:: bash

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

**Development Tools**

.. code-block:: bash

   pip install pytest black flake8 mypy sphinx

**Pre-commit Hooks** (optional)

.. code-block:: bash

   pip install pre-commit
   pre-commit install

Running Tests
-------------

**Unit Tests**

.. code-block:: bash

   pytest tests/unit/

**Integration Tests**

.. code-block:: bash

   pytest tests/integration/

**All Tests with Coverage**

.. code-block:: bash

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

**Specific Test**

.. code-block:: bash

   pytest tests/test_adapter.py::test_load_input

Building Documentation
----------------------

.. code-block:: bash

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

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

Project Structure
-----------------

.. code-block:: text

   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!