todoapp-vgv7cg/CONTRIBUTING.md

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
• Development Setup
• Code Standards
• Making Changes
• Submitting Changes
• Database Migrations
• Testing Guidelines
• Code Review Process

Getting Started

Prerequisites

• Python 3.8+
• Git
• Basic knowledge of FastAPI, SQLAlchemy, and Alembic

Development Setup

1. Clone the repository

   git clone <repository-url>
   cd todoapp
   

2. Set up virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Set up environment variables

   cp .env.example .env
   # Edit .env with your local configuration
   

5. Run database migrations

   alembic upgrade head
   

6. Start the development server

   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:

# 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:

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:

   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:

# 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

   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

   ## 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

   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

   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

# 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! 🎉