(Feat): Initial Commit.

2026-01-05 22:11:58 +00:00
commit b9224dd031
21 changed files with 3259 additions and 0 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,221 @@
+# 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! 🎉