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
This commit is contained in:
Automated Action
parent
fc27731f56
commit
1adb4843a3
303
CONTRIBUTING.md
Normal file
303
CONTRIBUTING.md
Normal file
@ -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! 🚀
|
||||
Loading…
x
Reference in New Issue
Block a user