Contributing
============

Thanks for your interest in contributing to FastAPI Traffic! This guide will help
you get started.

Development Setup
-----------------

1. **Clone the repository:**

   .. code-block:: bash

      git clone https://gitlab.com/zanewalker/fastapi-traffic.git
      cd fastapi-traffic

2. **Install uv** (if you don't have it):

   .. code-block:: bash

      curl -LsSf https://astral.sh/uv/install.sh | sh

3. **Create a virtual environment and install dependencies:**

   .. code-block:: bash

      uv venv
      source .venv/bin/activate  # or .venv\Scripts\activate on Windows
      uv pip install -e ".[dev]"

4. **Verify everything works:**

   .. code-block:: bash

      pytest

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

Run the full test suite:

.. code-block:: bash

   pytest

Run with coverage:

.. code-block:: bash

   pytest --cov=fastapi_traffic --cov-report=html

Run specific tests:

.. code-block:: bash

   pytest tests/test_algorithms.py
   pytest -k "test_token_bucket"

Code Style
----------

We use ruff for linting and formatting:

.. code-block:: bash

   # Check for issues
   ruff check .

   # Auto-fix issues
   ruff check --fix .

   # Format code
   ruff format .

Type Checking
-------------

We use pyright for type checking:

.. code-block:: bash

   pyright

The codebase is strictly typed. All public APIs should have complete type hints.

Making Changes
--------------

1. **Create a branch:**

   .. code-block:: bash

      git checkout -b feature/my-feature

2. **Make your changes.** Follow the existing code style.

3. **Add tests.** All new features should have tests.

4. **Run the checks:**

   .. code-block:: bash

      ruff check .
      ruff format .
      pyright
      pytest

5. **Commit your changes:**

   .. code-block:: bash

      git commit -m "feat: add my feature"

   We follow `Conventional Commits <https://www.conventionalcommits.org/>`_:

   - ``feat:`` New features
   - ``fix:`` Bug fixes
   - ``docs:`` Documentation changes
   - ``style:`` Code style changes (formatting, etc.)
   - ``refactor:`` Code refactoring
   - ``test:`` Adding or updating tests
   - ``chore:`` Maintenance tasks

6. **Push and create a merge request:**

   .. code-block:: bash

      git push origin feature/my-feature

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

.. code-block:: text

   fastapi-traffic/
   ├── fastapi_traffic/
   │   ├── __init__.py          # Public API exports
   │   ├── exceptions.py        # Custom exceptions
   │   ├── middleware.py        # Rate limit middleware
   │   ├── backends/
   │   │   ├── base.py          # Backend abstract class
   │   │   ├── memory.py        # In-memory backend
   │   │   ├── sqlite.py        # SQLite backend
   │   │   └── redis.py         # Redis backend
   │   └── core/
   │       ├── algorithms.py    # Rate limiting algorithms
   │       ├── config.py        # Configuration classes
   │       ├── config_loader.py # Configuration loading
   │       ├── decorator.py     # @rate_limit decorator
   │       ├── limiter.py       # Main RateLimiter class
   │       └── models.py        # Data models
   ├── tests/
   │   ├── test_algorithms.py
   │   ├── test_backends.py
   │   ├── test_decorator.py
   │   └── ...
   ├── examples/
   │   ├── 01_quickstart.py
   │   └── ...
   └── docs/
       └── ...

Guidelines
----------

**Code:**

- Keep functions focused and small
- Use descriptive variable names
- Add docstrings to public functions and classes
- Follow existing patterns in the codebase

**Tests:**

- Test both happy path and edge cases
- Use descriptive test names
- Mock external dependencies (Redis, etc.)
- Keep tests fast and isolated

**Documentation:**

- Update docs when adding features
- Include code examples
- Keep language clear and concise

Reporting Issues
----------------

Found a bug? Have a feature request? Please open an issue on GitLab:

https://gitlab.com/zanewalker/fastapi-traffic/issues

Include:

- What you expected to happen
- What actually happened
- Steps to reproduce
- Python version and OS
- FastAPI Traffic version

Questions?
----------

Feel free to open an issue for questions. We're happy to help!