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:

   git clone https://github.com/yourusername/todoapp.git
   cd todoapp
   

3. Create a virtual environment:

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

4. Install dependencies:

   pip install -r requirements.txt
   

5. Set up the database:

   alembic upgrade head
   

6. Run the application:

   uvicorn main:app --reload
   

🔧 Development Workflow

Making Changes

1. Create a new branch for your feature or bugfix:

   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:

   git add .
   git commit -m "Add feature: description of your changes"
   

5. Push to your fork:

   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:

# 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

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:

   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:

   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:

   alembic revision --autogenerate -m "Description of changes"
   

3. Review the generated migration file
4. Test the migration:

   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:

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