From afd59452e1b4f94af98eb4da02fbed5e472850d6 Mon Sep 17 00:00:00 2001 From: Automated Action Date: Wed, 18 Jun 2025 01:17:41 +0000 Subject: [PATCH] Add comprehensive CONTRIBUTING.md guide --- CONTRIBUTING.md | 268 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9e13eba --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,268 @@ +# Contributing to Simple Todo API + +Thank you for your interest in contributing to the Simple Todo API! This document provides guidelines for contributing to this FastAPI project. + +## Table of Contents + +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [Code Standards](#code-standards) +- [Making Changes](#making-changes) +- [Submitting Changes](#submitting-changes) +- [Database Migrations](#database-migrations) +- [Testing Guidelines](#testing-guidelines) +- [Code Review Process](#code-review-process) + +## Getting Started + +### Prerequisites + +- Python 3.8+ +- Git +- Basic knowledge of FastAPI, SQLAlchemy, and Alembic + +### Development Setup + +1. **Clone the repository** + ```bash + git clone + cd todoapp + ``` + +2. **Set up virtual environment** + ```bash + python -m venv venv + source venv/bin/activate # On Windows: venv\Scripts\activate + ``` + +3. **Install dependencies** + ```bash + pip install -r requirements.txt + ``` + +4. **Set up environment variables** + ```bash + cp .env.example .env + # Edit .env with your local configuration + ``` + +5. **Run database migrations** + ```bash + alembic upgrade head + ``` + +6. **Start the development server** + ```bash + uvicorn main:app --reload + ``` + +## Code Standards + +### Code Formatting + +We use **Ruff** for code formatting and linting. Please ensure your code is properly formatted before submitting: + +```bash +# Check and fix linting issues +ruff check . --fix + +# Format code +ruff format . +``` + +### Code Style Guidelines + +- Follow PEP 8 conventions +- Use type hints for all function parameters and return values +- Write descriptive variable and function names +- Keep functions small and focused on a single responsibility +- Add docstrings for public functions and classes + +### Import Organization + +- Standard library imports first +- Third-party library imports second +- Local application imports last +- Use absolute imports when possible + +Example: +```python +from typing import List, Optional +from fastapi import APIRouter, Depends +from sqlalchemy.orm import Session + +from app.crud import todo as todo_crud +from app.models.todo import Todo +``` + +## Making Changes + +### Branching Strategy + +1. Create a new branch for your feature/fix: + ```bash + git checkout -b feature/your-feature-name + # or + git checkout -b fix/your-bug-fix + ``` + +2. Make your changes following the code standards +3. Test your changes thoroughly +4. Commit your changes with descriptive messages + +### Commit Messages + +Use clear, descriptive commit messages: + +```bash +# Good examples +git commit -m "Add user authentication endpoints" +git commit -m "Fix pagination bug in todo listing" +git commit -m "Update README with new API endpoints" + +# Avoid +git commit -m "Fix stuff" +git commit -m "Update" +``` + +## Submitting Changes + +### Pull Request Process + +1. **Ensure your code follows all standards** + ```bash + ruff check . --fix + ruff format . + ``` + +2. **Update documentation if needed** + - Update README.md for new features + - Update API documentation + - Add/update docstrings + +3. **Create a pull request** + - Provide a clear title and description + - Reference any related issues + - Include screenshots for UI changes (if applicable) + +4. **Pull request template** + ```markdown + ## Description + Brief description of changes + + ## Type of Change + - [ ] Bug fix + - [ ] New feature + - [ ] Breaking change + - [ ] Documentation update + + ## Testing + - [ ] Tests pass locally + - [ ] Code has been formatted with Ruff + - [ ] Documentation updated + + ## Additional Notes + Any additional information or context + ``` + +## Database Migrations + +### Creating Migrations + +When making database schema changes: + +1. **Create a new migration** + ```bash + alembic revision -m "Description of your change" + ``` + +2. **Edit the migration file** + - Add proper upgrade() and downgrade() functions + - Test both upgrade and downgrade paths + +3. **Apply the migration** + ```bash + alembic upgrade head + ``` + +### Migration Guidelines + +- Always provide both upgrade and downgrade functions +- Use descriptive migration messages +- Test migrations on a copy of production data when possible +- Never edit existing migration files once they're merged + +## Testing Guidelines + +### Writing Tests + +- Write tests for all new functionality +- Follow the existing test structure +- Use descriptive test names +- Test both success and failure cases + +### Running Tests + +```bash +# Run all tests +pytest + +# Run specific test file +pytest tests/test_todos.py + +# Run with coverage +pytest --cov=app +``` + +## Code Review Process + +### For Contributors + +- Respond to review feedback promptly +- Make requested changes in new commits (don't force push) +- Ask questions if feedback is unclear + +### For Reviewers + +- Be constructive and specific in feedback +- Focus on code quality, security, and maintainability +- Approve when standards are met + +## Project Structure Guidelines + +### Adding New Features + +When adding new features, follow the existing structure: + +``` +app/ +├── api/v1/ # API endpoints +├── crud/ # Database operations +├── db/ # Database configuration +├── models/ # SQLAlchemy models +└── schemas/ # Pydantic schemas +``` + +### File Naming Conventions + +- Use snake_case for Python files +- Use descriptive names that indicate purpose +- Group related functionality in modules + +## Getting Help + +If you need help or have questions: + +1. Check existing documentation +2. Search existing issues +3. Create a new issue with the "question" label +4. Reach out to maintainers + +## Recognition + +Contributors will be recognized in: +- CONTRIBUTORS.md file +- Release notes for significant contributions +- Project documentation + +Thank you for contributing to Simple Todo API! 🎉 \ No newline at end of file