222 lines
4.6 KiB
Markdown
222 lines
4.6 KiB
Markdown
# Contributing to FastAPI Route Loader
|
|
|
|
Thank you for your interest in contributing to fastapi-route-loader! This document provides guidelines and instructions for contributing.
|
|
|
|
## Development Setup
|
|
|
|
1. **Clone the repository**
|
|
```bash
|
|
git clone https://github.com/yourusername/fastapi-route-loader.git
|
|
cd fastapi-route-loader
|
|
```
|
|
|
|
2. **Set up the development environment**
|
|
```bash
|
|
# Run the setup script
|
|
bash scripts/setup.sh
|
|
|
|
# Or manually:
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
3. **Verify the setup**
|
|
```bash
|
|
bash scripts/verify.sh
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Run all tests
|
|
pytest
|
|
|
|
# Run with coverage
|
|
pytest --cov=fastapi_route_loader --cov-report=html
|
|
|
|
# Run specific test file
|
|
pytest tests/test_container.py
|
|
|
|
# Run specific test
|
|
pytest tests/test_container.py::TestRouterContainer::test_add_router
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
We use strict linting and type checking:
|
|
|
|
```bash
|
|
# Run ruff linter
|
|
ruff check .
|
|
|
|
# Auto-fix issues
|
|
ruff check --fix .
|
|
|
|
# Format code
|
|
ruff format .
|
|
|
|
# Run type checker
|
|
pyright
|
|
```
|
|
|
|
### Code Style Guidelines
|
|
|
|
- **Type Hints**: All functions must have complete type hints
|
|
- **Docstrings**: All public functions and classes must have docstrings
|
|
- **Line Length**: Maximum 88 characters (enforced by ruff)
|
|
- **Imports**: Use absolute imports, organized by ruff
|
|
- **Python Version**: Code must be compatible with Python 3.10+
|
|
|
|
### Commit Messages
|
|
|
|
Follow conventional commit format:
|
|
|
|
```
|
|
<type>(<scope>): <subject>
|
|
|
|
<body>
|
|
|
|
<footer>
|
|
```
|
|
|
|
Types:
|
|
- `feat`: New feature
|
|
- `fix`: Bug fix
|
|
- `docs`: Documentation changes
|
|
- `test`: Test changes
|
|
- `refactor`: Code refactoring
|
|
- `style`: Code style changes
|
|
- `chore`: Build/tooling changes
|
|
|
|
Example:
|
|
```
|
|
feat(container): add support for router priorities
|
|
|
|
Add ability to set priority levels for routers to control
|
|
loading order.
|
|
|
|
Closes #123
|
|
```
|
|
|
|
## Pull Request Process
|
|
|
|
1. **Create a feature branch**
|
|
```bash
|
|
git checkout -b feature/your-feature-name
|
|
```
|
|
|
|
2. **Make your changes**
|
|
- Write tests for new functionality
|
|
- Update documentation as needed
|
|
- Ensure all tests pass
|
|
- Ensure code passes linting and type checking
|
|
|
|
3. **Run verification**
|
|
```bash
|
|
bash scripts/verify.sh
|
|
```
|
|
|
|
4. **Commit your changes**
|
|
```bash
|
|
git add .
|
|
git commit -m "feat: your feature description"
|
|
```
|
|
|
|
5. **Push to your fork**
|
|
```bash
|
|
git push origin feature/your-feature-name
|
|
```
|
|
|
|
6. **Create a Pull Request**
|
|
- Provide a clear description of the changes
|
|
- Reference any related issues
|
|
- Ensure CI checks pass
|
|
|
|
## Testing Guidelines
|
|
|
|
### Writing Tests
|
|
|
|
- Place tests in the `tests/` directory
|
|
- Name test files as `test_*.py`
|
|
- Use descriptive test names: `test_<functionality>_<scenario>`
|
|
- Group related tests in classes
|
|
- Use fixtures for common setup
|
|
|
|
Example:
|
|
```python
|
|
class TestRouterContainer:
|
|
def test_add_router_success(self):
|
|
container = RouterContainer()
|
|
router = APIRouter()
|
|
container.add_router("test", router)
|
|
assert container.has_router("test")
|
|
|
|
def test_add_router_duplicate_raises_error(self):
|
|
container = RouterContainer()
|
|
router = APIRouter()
|
|
container.add_router("test", router)
|
|
with pytest.raises(ValueError):
|
|
container.add_router("test", router)
|
|
```
|
|
|
|
### Test Coverage
|
|
|
|
- Aim for >90% code coverage
|
|
- Test both success and error cases
|
|
- Test edge cases and boundary conditions
|
|
- Test integration scenarios
|
|
|
|
## Documentation
|
|
|
|
### Docstring Format
|
|
|
|
Use Google-style docstrings:
|
|
|
|
```python
|
|
def add_router(self, name: str, router: APIRouter, metadata: dict[str, Any] | None = None) -> None:
|
|
"""Add a router to the container.
|
|
|
|
Args:
|
|
name: Unique name for the router
|
|
router: APIRouter instance
|
|
metadata: Optional metadata for the event
|
|
|
|
Raises:
|
|
ValueError: If router name already exists
|
|
|
|
Example:
|
|
>>> container = RouterContainer()
|
|
>>> router = APIRouter()
|
|
>>> container.add_router("users", router)
|
|
"""
|
|
```
|
|
|
|
### Updating Documentation
|
|
|
|
- Update README.md for user-facing changes
|
|
- Update docstrings for API changes
|
|
- Add examples for new features
|
|
- Update CHANGELOG.md
|
|
|
|
## Release Process
|
|
|
|
1. Update version in `pyproject.toml`
|
|
2. Update CHANGELOG.md
|
|
3. Create a git tag: `git tag v0.1.0`
|
|
4. Push tag: `git push origin v0.1.0`
|
|
5. Create GitHub release
|
|
6. Publish to PyPI (maintainers only)
|
|
|
|
## Questions?
|
|
|
|
Feel free to open an issue for:
|
|
- Bug reports
|
|
- Feature requests
|
|
- Questions about contributing
|
|
- General discussion
|
|
|
|
Thank you for contributing! 🎉
|