Thank you for your interest in contributing to MBTQ Auto-API! This document provides guidelines and instructions for contributing.
- Code of Conduct
- Getting Started
- Development Setup
- Making Changes
- Testing
- Documentation
- Pull Request Process
- Style Guide
We are committed to providing a welcoming and inclusive environment for all contributors, regardless of:
- Experience level
- Gender identity and expression
- Sexual orientation
- Disability
- Personal appearance
- Body size
- Race, ethnicity, or nationality
- Age
- Religion
- Be respectful and considerate
- Use welcoming and inclusive language
- Accept constructive criticism gracefully
- Focus on what is best for the community
- Show empathy towards others
- Python 3.11 or higher
- Git
- Basic understanding of FastAPI and async Python
- Familiarity with REST APIs
We welcome contributions in these areas:
- Bug Fixes: Fix issues in existing code
- New Features: Implement planned or new features
- Documentation: Improve or add documentation
- Tests: Add or improve test coverage
- Performance: Optimize existing code
- Security: Identify and fix security issues
# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/Auto-API.git
cd Auto-API# Create virtual environment
python3 -m venv venv
# Activate it
source venv/bin/activate # On Windows: venv\Scripts\activate# Install project dependencies
pip install -r requirements.txt
# Install development dependencies (if available)
pip install pytest pytest-asyncio pytest-cov black flake8# Copy example environment file
cp .env.example .env
# Edit .env with your settings (if needed)# Start the development server
./start_server.sh
# Or manually
uvicorn main:app --reload# Test that the server is running
curl http://localhost:8000/api/health
# Run tests (if available)
python test_api.py# Create a new branch for your changes
git checkout -b feature/your-feature-name
# Or for bug fixes
git checkout -b fix/bug-descriptionFollow these guidelines:
Auto-API/
├── main.py # FastAPI application (add endpoints here)
├── models.py # Pydantic models (add data models here)
├── config.py # Configuration (add settings here)
├── services/ # Service layer
│ ├── deafauth.py # Authentication service
│ ├── fibonrose.py # Logging/reputation service
│ ├── pinksync.py # Deployment service
│ └── code_generator.py # Code generation service
└── tests/ # Test files (create this directory)
- Define the model in
models.py:
class NewFeatureRequest(BaseModel):
field1: str
field2: int- Add the endpoint in
main.py:
@app.post("/api/new-feature")
async def new_feature(request: NewFeatureRequest, user: dict = Depends(verify_auth)):
# Your implementation
await fibonrose_service.log_event("new_feature", {}, user["username"])
return {"success": True}- Update documentation:
- Add to API_GUIDE.md
- Update README.md if needed
- Create a new file in
services/:
# services/new_service.py
class NewService:
def __init__(self):
pass
async def health_check(self) -> str:
return "healthy"
async def do_something(self, param: str) -> Dict:
# Implementation
pass- Import in
main.py:
from services.new_service import NewService
new_service = NewService()Create tests for your changes:
# tests/test_new_feature.py
import pytest
from httpx import AsyncClient
from main import app
@pytest.mark.asyncio
async def test_new_feature():
async with AsyncClient(app=app, base_url="http://test") as client:
# Authenticate first
auth_response = await client.post(
"/api/auth/login",
json={"username": "testuser"}
)
token = auth_response.json()["token"]
# Test your endpoint
response = await client.post(
"/api/new-feature",
headers={"X-MBTQ-Token": token},
json={"field1": "value", "field2": 123}
)
assert response.status_code == 200
assert response.json()["success"] == TrueIf your changes affect the API:
- Update API_GUIDE.md with new endpoint documentation
- Update README.md if adding major features
- Update CHANGELOG.md under [Unreleased]
- Add docstrings to new functions/classes
# Run all tests
pytest
# Run with coverage
pytest --cov=. --cov-report=html
# Run specific test file
pytest tests/test_new_feature.py- Test both success and failure cases
- Test edge cases
- Test authentication/authorization
- Test input validation
- Use meaningful test names
- Keep tests independent
# Start the server
uvicorn main:app --reload
# Test endpoints manually
curl -X POST http://localhost:8000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"username": "testuser"}'Use docstrings for all public functions and classes:
async def example_function(param: str) -> Dict:
"""
Brief description of what this function does.
Args:
param: Description of the parameter
Returns:
Dict containing the result with keys:
- success: Boolean indicating success
- data: The actual data
Raises:
HTTPException: If validation fails
"""
passFastAPI generates automatic documentation, but also update:
- API_GUIDE.md: Detailed endpoint documentation
- README.md: High-level usage examples
- ARCHITECTURE.md: For architectural changes
# Stage your changes
git add .
# Commit with a clear message
git commit -m "Add: Brief description of changes"
# Use conventional commit prefixes:
# - Add: New feature
# - Fix: Bug fix
# - Update: Update existing feature
# - Remove: Remove feature/code
# - Docs: Documentation only
# - Test: Add/update tests
# - Refactor: Code refactoringgit push origin feature/your-feature-name- Go to the original repository on GitHub
- Click "New Pull Request"
- Select your fork and branch
- Fill in the PR template:
## Description
Brief description of changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
## Testing
- [ ] All tests pass
- [ ] New tests added
- [ ] Manual testing completed
## Checklist
- [ ] Code follows style guide
- [ ] Documentation updated
- [ ] No new warnings
- [ ] Security considerations addressed- Respond to reviewer comments
- Make requested changes
- Push updates to the same branch
# Update your main branch
git checkout main
git pull upstream main
# Delete your feature branch
git branch -d feature/your-feature-nameFollow PEP 8 with these specifics:
# Use 4 spaces for indentation (no tabs)
def example():
pass
# Max line length: 100 characters
# Use black for formatting
black main.py
# Check with flake8
flake8 main.py# Classes: PascalCase
class MyService:
pass
# Functions/Variables: snake_case
def my_function():
my_variable = "value"
# Constants: UPPER_CASE
MAX_RETRIES = 3
# Private: _leading_underscore
def _private_helper():
passAlways use type hints:
from typing import Optional, Dict, List
async def fetch_data(
user_id: str,
limit: int = 10
) -> Dict[str, Any]:
passUse async/await consistently:
# Good
async def fetch_data():
async with httpx.AsyncClient() as client:
response = await client.get(url)
return response.json()
# Avoid mixing sync/async without good reason- Use proper heading hierarchy
- Include code examples
- Add links where appropriate
- Use lists for clarity
# Good: Explain WHY, not WHAT
# Calculate reputation based on recent activity
score = sum(log["impact"] for log in recent_logs)
# Avoid: Obvious comments
# Bad: Set score to sum of impacts
score = sum(log["impact"] for log in recent_logs)Good commit messages:
Add: User authentication endpoint
- Implement token generation
- Add token validation
- Update documentation
Closes #123
Bad commit messages:
fix stuff
update
changes
Contributors will be:
- Listed in the repository contributors
- Acknowledged in release notes
- Credited in CHANGELOG.md
If you have questions:
- Check existing documentation
- Search existing issues
- Ask in a new issue with the "question" label
By contributing, you agree that your contributions will be licensed under the MIT License.
Thank you for contributing to MBTQ Auto-API! 🎯