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](#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 <repository-url>
   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! 🎉