Contributing¶

Thank you for considering contributing to FastAPI Shield! This document provides guidelines and instructions for contributing to the project.

Code of Conduct¶

By participating in this project, you agree to abide by our Code of Conduct. Please be respectful and considerate of others.

Prerequisites¶

Python 3.9 or higher
pip, uv, or poetry
Git

Setting Up Development Environment¶

Fork the repository on GitHub

Clone your fork locally

git clone https://github.com/yourusername/fastapi-shield.git
cd fastapi-shield

Set up a virtual environment and install dependencies using one of the following methods:

Using venv and pip:

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

Using uv:

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

Using poetry:

poetry install

Set up pre-commit hooks:
```
pre-commit install
```

Development Workflow¶

Create a new branch for your feature or bugfix:
```
git checkout -b feature-or-bugfix-name
```
Make your changes, writing tests as needed
Run the tests:
```
nox
```

Or run a specific test session:

nox -s tests

Make sure the code is properly formatted and linted:
```
nox -s lint
```
Commit your changes following the Conventional Commits specification:
```
git commit -m "feat: add new feature"
```

Some common prefixes include: - feat: for new features - fix: for bug fixes - docs: for documentation changes - test: for changes to tests - refactor: for code refactoring

Push your branch:
```
git push origin feature-or-bugfix-name
```
Create a Pull Request on GitHub

Pull Request Guidelines¶

All tests must pass before a PR can be merged
Include tests for any new functionality
Update documentation for any new features or API changes
Keep changes focused and specific
Ensure your code adheres to the project's style guidelines (enforced by pre-commit hooks)

Setting Up Documentation¶

To build and test the documentation locally:

Install documentation dependencies:
```
pip install -e ".[docs]"
```
Build and serve the documentation:
```
mkdocs serve
```
Open http://127.0.0.1:8000 in your browser to view the documentation

Code Style Guidelines¶

This project uses:

Ruff for linting and formatting
Black for code formatting
isort for import sorting
mypy for static type checking

Pre-commit hooks are configured to enforce these standards automatically when you commit code.

Testing Guidelines¶

Write tests for all new functionality
Use pytest for writing tests
Aim for high test coverage
Include both unit tests and integration tests
Use meaningful test names that describe what's being tested

Submitting Issues¶

When submitting an issue, please:

Check if the issue already exists
Include a clear title and description
Add steps to reproduce the issue
Include the version of FastAPI Shield, FastAPI, and Python you're using
Add any relevant code snippets or error messages

Getting Help¶

If you have questions or need help, you can:

Open an issue on GitHub
Discussion forums (if available)
Reach out to the maintainers directly

Thank you for contributing to FastAPI Shield!