# Contributing to persidict

Thank you for your interest in contributing to `persidict`! 
Your help is greatly appreciated. These guidelines will help you get started.

## Getting Started

1. **Learn the Foundations:**
   Familiarize yourself with the project's [design](https://github.com/pythagoras-dev/persidict/blob/master/design_principles.md)
   principles, [docstrings and comments](https://github.com/pythagoras-dev/persidict/blob/master/docstrings_and_comments.md) guidelines,
   [type hints](https://github.com/pythagoras-dev/persidict/blob/master/type_hints.md) guidelines,
   and [unit testing](https://github.com/pythagoras-dev/persidict/blob/master/unit_tests.md) guide.


2. **Fork and Clone:**
    ```bash
    git clone https://github.com/your-username/persidict.git
    cd persidict
    ```

2.  **Install Dependencies:**
    We use `uv` for package management.
    ```bash
    uv pip install -e ".[dev]"
    ```

3.  **Run Tests:**
    Make sure the test suite passes before making changes.
    ```bash
    pytest
    ```
    
4.  **Run Linting:**
    Make sure the code is free of linting errors.
    ```bash
    uv run ruff check .
    ```

## How to Contribute

*   **Report Bugs:** Use the GitHub issue tracker to report bugs. 
Please provide a clear description, steps to reproduce, and your Python version.
*   **Suggest Enhancements:** Open an issue to discuss new features or improvements.

### Submitting Pull Requests

1.  **Create a Branch:**
    ```bash
    git checkout -b your-feature-name
    ```
2.  **Make Changes:** Write your code and add corresponding tests in the `tests/` directory.
3.  **Follow Code Style:**
    *   Adhere to PEP 8 guidelines.
    *   Write clear, Google-style docstrings for public functions and classes.
    *   Add type hints where appropriate.
    *   Use keyword-only parameters for new public methods and constructors — see [Section 9 of design_principles.md](https://github.com/pythagoras-dev/persidict/blob/master/design_principles.md#9-keyword-only-parameters-by-default).
4. **Check Tests:** Make sure the test suite passes.
5. **Check Linting:** Make sure the code is free of linting errors.
6. **Write Commit Messages:** Follow the conventions below.
7. **Push and Open a Pull Request:** Push your branch to your fork and open a pull request.

### Commit Message Prefixes

Use these prefixes for your commit messages:

| Prefix           | Description                        |
|:-----------------|:-----------------------------------|
| `ENH:`           | Enhancement, new functionality     |
| `FIX: (was BUG)` | Bug fix                            |
| `DOC:`           | Additions/updates to documentation |
| `TST:`           | Additions/updates to tests         |
| `BLD:`           | Build process/script updates       |
| `PERF:`          | Performance improvement            |
| `REF:`           | Refactoring                        |
| `TYP:`           | Type annotations                   |
| `CLN:`           | Code cleanup                       |

*Example: `ENH: Add support for nested parameter validation`*

## License

By contributing, you confirm that your contributions are an original work,
or you have permission to use it, and agree that it will be 
licensed under the MIT License.

## Questions?

Feel free to open an issue or contact the maintainer, Vlad (Volodymyr) Pavlov.