todoapp-zj3gfs/CONTRIBUTING.md

# Contributing to Todo API

We welcome contributions to the Todo API project! This document provides guidelines for contributing to the project.

## 🚀 Getting Started

### Prerequisites
- Python 3.8 or higher
- Git
- Basic knowledge of FastAPI and SQLAlchemy

### Development Setup

1. **Fork the repository** on GitHub

2. **Clone your fork:**
   ```bash
   git clone https://github.com/yourusername/todoapp.git
   cd todoapp
   ```

3. **Create a virtual environment:**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

4. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

5. **Set up the database:**
   ```bash
   alembic upgrade head
   ```

6. **Run the application:**
   ```bash
   uvicorn main:app --reload
   ```

## 🔧 Development Workflow

### Making Changes

1. **Create a new branch** for your feature or bugfix:
   ```bash
   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/bug-description
   ```

2. **Make your changes** following the coding standards below

3. **Test your changes** thoroughly

4. **Commit your changes** with a descriptive commit message:
   ```bash
   git add .
   git commit -m "Add feature: description of your changes"
   ```

5. **Push to your fork:**
   ```bash
   git push origin feature/your-feature-name
   ```

6. **Create a Pull Request** on GitHub

### Branch Naming Convention

- **Features:** `feature/feature-name`
- **Bug fixes:** `fix/bug-description`
- **Documentation:** `docs/update-description`
- **Refactoring:** `refactor/component-name`

## 📝 Coding Standards

### Code Style

This project uses **Ruff** for linting and formatting. Please ensure your code passes all checks:

```bash
# Check for linting issues
ruff check .

# Auto-format code
ruff format .
```

### Code Guidelines

1. **Follow PEP 8** Python style guide
2. **Use type hints** for all function parameters and return values
3. **Write descriptive variable and function names**
4. **Keep functions focused and small**
5. **Add docstrings** for classes and public methods
6. **Use meaningful commit messages**

### Example Code Structure

```python
from typing import Optional
from fastapi import HTTPException
from sqlalchemy.orm import Session

def get_todo_by_id(db: Session, todo_id: int) -> Optional[Todo]:
    """
    Retrieve a todo item by its ID.
    
    Args:
        db: Database session
        todo_id: The ID of the todo item
        
    Returns:
        Todo object if found, None otherwise
    """
    return db.query(Todo).filter(Todo.id == todo_id).first()
```

## 🧪 Testing

### Running Tests

Currently, the project doesn't have automated tests. Contributing test cases is highly welcomed!

### Manual Testing

1. **Start the server:**
   ```bash
   uvicorn main:app --reload
   ```

2. **Test the API endpoints:**
   - Visit `http://localhost:8000/docs` for interactive testing
   - Use curl or Postman to test endpoints
   - Verify database operations work correctly

3. **Test database migrations:**
   ```bash
   alembic upgrade head
   alembic downgrade -1
   alembic upgrade head
   ```

## 📋 Types of Contributions

We welcome various types of contributions:

### 🐛 Bug Reports

When reporting bugs, please include:
- **Clear description** of the issue
- **Steps to reproduce** the bug
- **Expected vs actual behavior**
- **Environment details** (Python version, OS, etc.)
- **Error messages** or logs if applicable

### ✨ Feature Requests

For new features, please provide:
- **Clear description** of the proposed feature
- **Use case** and benefits
- **Possible implementation approach**
- **Any breaking changes** it might introduce

### 🔧 Code Contributions

Priority areas for contributions:
- **Unit and integration tests**
- **Authentication and authorization**
- **Input validation improvements**
- **Performance optimizations**
- **Documentation improvements**
- **Error handling enhancements**

### 📚 Documentation

Help improve documentation by:
- **Fixing typos** or unclear explanations
- **Adding examples** and use cases
- **Improving API documentation**
- **Creating tutorials** or guides

## 🏗 Architecture Guidelines

### Project Structure

```
todoapp/
├── main.py                 # FastAPI app entry point
├── app/
│   ├── db/                # Database configuration
│   ├── models/            # SQLAlchemy models
│   ├── schemas/           # Pydantic schemas
│   ├── crud/              # Database operations (future)
│   └── api/               # API routes (future)
├── alembic/               # Database migrations
└── tests/                 # Test files (future)
```

### Adding New Features

When adding new features:

1. **Create appropriate models** in `app/models/`
2. **Define Pydantic schemas** in `app/schemas/`
3. **Add database operations** (consider creating `app/crud/`)
4. **Create API endpoints** in `main.py` or `app/api/`
5. **Write migration scripts** in `alembic/versions/`
6. **Update documentation** as needed

## 📊 Database Changes

### Creating Migrations

1. **Make changes** to SQLAlchemy models
2. **Generate migration:**
   ```bash
   alembic revision --autogenerate -m "Description of changes"
   ```
3. **Review the generated migration** file
4. **Test the migration:**
   ```bash
   alembic upgrade head
   ```

### Migration Best Practices

- **Always review** auto-generated migrations
- **Test migrations** on sample data
- **Write descriptive migration messages**
- **Consider backward compatibility**
- **Include both upgrade and downgrade paths**

## 🤝 Pull Request Process

### Before Submitting

- [ ] Code follows the project's coding standards
- [ ] All linting checks pass (`ruff check .`)
- [ ] Code is properly formatted (`ruff format .`)
- [ ] Commit messages are descriptive
- [ ] Documentation is updated if needed
- [ ] Manual testing has been performed

### Pull Request Template

When creating a pull request, please include:

```markdown
## Description
Brief description of changes made

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring
- [ ] Other (specify)

## Testing
Describe how you tested your changes

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes (or documented)
```

## 📞 Getting Help

If you need help or have questions:

1. **Check existing issues** on GitHub
2. **Create a new issue** with your question
3. **Join discussions** in existing issues
4. **Review the documentation** in the README

## 🎯 Good First Issues

New contributors can start with:

- **Adding input validation**
- **Improving error messages**
- **Writing unit tests**
- **Fixing documentation typos**
- **Adding API endpoint examples**

## 📜 Code of Conduct

Please be respectful and professional in all interactions. We're here to build great software together!

### Guidelines

- **Be respectful** of different viewpoints and experiences
- **Accept constructive criticism** gracefully
- **Focus on what's best** for the community and project
- **Show empathy** towards other contributors

Thank you for contributing to Todo API! 🚀