From 1adb4843a3709fc46122f9bbdcfce1158194133c Mon Sep 17 00:00:00 2001 From: Automated Action Date: Tue, 17 Jun 2025 08:39:31 +0000 Subject: [PATCH] Add comprehensive CONTRIBUTING.md guidelines - Include development setup and workflow instructions - Add coding standards and style guidelines - Document pull request process and templates - Provide architecture guidelines for new features - Include database migration best practices - Add code of conduct and community guidelines --- CONTRIBUTING.md | 303 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fd8d426 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,303 @@ +# 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! ๐Ÿš€ \ No newline at end of file