Development Workflow

Guidelines for efficient development in the Definable backend project

This guide outlines the recommended development workflow for the Definable backend project. Following these practices will help maintain code quality and ensure smooth collaboration.

Development Environment

Before starting development, ensure you have:

1. Completed the installation process
2. Set up your environment variables
3. Installed pre-commit hooks with pre-commit install

Git Workflow

We follow a branch-based workflow to manage code changes:

Branching Strategy

• Main Branch: Always contains stable, production-ready code
• Dev Branch: All new features and bug fixes are merged in the dev branch then escalated further.
• Feature Branches: For new features (feat/feature-name)
• Bugfix Branches: For bug fixes (fix/issue-id)
• Release Branches: For preparing releases (release/v1.2.3)

Branch Naming Convention

• feat/short-description - For new features
• fix/issue-id - For bug fixes
• refactor/component-name - For code refactoring
• docs/what-changed - For documentation updates

Code Change Process

1. Create a New Branch

git checkout main
git pull
git checkout -b feature/my-new-feature

2. Make Changes

Write your code following the project’s coding standards (enforced by Ruff and Mypy).

3. Run Tests Locally

# Run unit tests
pytest tests/unit

# Run integration tests
pytest tests/integration

# Run with coverage
pytest --cov=src tests/

4. Commit Changes

# Add files
git add .

# Commit (this will trigger pre-commit hooks)
git commit -m "Add feature: detailed description"

The pre-commit hooks will run Ruff for linting and Mypy for type checking. Fix any issues before proceeding.

5. Push Changes

git push origin feature/my-new-feature

6. Create a Pull Request

Create a pull request on GitHub with:

• Clear title describing the change
• Detailed description of what was changed and why
• References to any related issues
• Ensure the PR is directed to the dev branch for review.

7. Code Review

All pull requests require at least one review before merging into dev. Reviewers should check:

• Code correctness
• Test coverage
• Adherence to project standards
• Documentation

8. Merge

Once approved, the PR can be merged into the dev branch. After sufficient testing and validation, changes can be merged into master and then into the release branch.

Code Quality Standards

Style Guide

We use Ruff for linting with the following key rules:

• 2-space indentation
• 150 character line length
• Python 3.10+ features allowed

Type Annotations

All code should use type annotations and pass Mypy checks:

def add_user(name: str, age: int) -> User:
    """
    Create a new user.
    
    Args:
        name: The user's name
        age: The user's age
    
    Returns:
        A new User instance
    """
    return User(name=name, age=age)

Documentation

All modules, classes, and functions should have docstrings following Google’s style guide:

def function(arg1: str, arg2: int) -> bool:
    """Short description of function.
    
    Longer description explaining the function's purpose and any
    notable behavior.
    
    Args:
        arg1: Description of arg1
        arg2: Description of arg2
    
    Returns:
        Description of return value
        
    Raises:
        ValueError: Description of when this error is raised
    """

Adding New Components

Adding a New Service

1. Create a new directory in src/services/[service_name]/
2. Add the required files:
   • service.py - Main service implementation
   • schema.py - Pydantic models

Example service structure:

from fastapi import Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession

from database import get_db
from services.__base.acquire import Acquire

from .schema import MyRequestSchema, MyResponseSchema

class MyNewService:
    """My new service description."""

    http_exposed = ["get=resource", "post=resource"]

    def __init__(self, acquire: Acquire):
        """Initialize service."""
        self.acquire = acquire
        self.logger = acquire.logger
        
    async def get_resource(
        self, 
        resource_id: str, 
        session: AsyncSession = Depends(get_db)
    ) -> MyResponseSchema:
        """Get a resource by ID."""
        # Implementation

Adding a New Model

1. Create a new file in src/models/ named [model_name]_model.py
2. Define your SQLAlchemy model
3. Update src/models/__init__.py to export your model

Example model:

from sqlalchemy import Column, Integer, String, ForeignKey
from sqlalchemy.dialects.postgresql import UUID
from uuid import uuid4

from database.models import Base, CRUD

class MyNewModel(Base, CRUD):
    """My new model description."""
    
    __tablename__ = "my_new_models"
    
    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid4)
    name = Column(String, nullable=False)
    description = Column(String)
    related_id = Column(UUID(as_uuid=True), ForeignKey("related_table.id"))

4. Create a migration:

alembic revision --autogenerate -m "Add my new model"
alembic upgrade head

Database Migrations

Creating Migrations

# Generate a migration based on model changes
alembic revision --autogenerate -m "Description of changes"

# Apply migrations
alembic upgrade head

# Revert migrations
alembic downgrade -1  # Revert one migration
alembic downgrade base  # Revert all migrations

Debugging

Logging

Use the logger provided by the Acquire class:

def my_function(self):
    self.logger.debug("Debug message with data", extra_field=value)
    self.logger.info("Info message")
    self.logger.warning("Warning message")
    self.logger.error("Error message", exc_info=True)

FastAPI Debug Mode

For local development, use FastAPI’s debug mode:

python -m src.app --dev

This enables auto-reload on code changes.

Deployment Pipeline

Our code follows this deployment pipeline:

1. Development

   Local development and testing

2. Continuous Integration

   Automated tests and checks run on GitHub Actions

3. Staging Deployment

   Automatic deployment to the staging environment after merging into the dev branch.

4. Production Deployment

   Manual approval and deployment to production

Troubleshooting

Pre-commit Hooks Failing

If pre-commit hooks are failing:

• Check Ruff errors: ruff check src/
• Check Mypy errors: mypy src/
• Fix the issues before committing again

Database Migration Issues

If you encounter migration errors:

• Check for model conflicts or circular imports
• Try recreating the migration with alembic revision --autogenerate -m "Fixed migration"
• In worst case, you can reset: alembic downgrade base then alembic upgrade head

Dependency Issues

If you encounter new dependency issues:

• Update Poetry: poetry update
• Check for locked versions: poetry show -o
• Add specific dependency: poetry add package-name
• Update lock file: poetry lock --no-update

Best Practices

1. Write tests first: Follow test-driven development when possible
2. Keep services focused: Each service should have a single responsibility
3. Use async properly: Ensure all I/O operations are async
4. Handle exceptions: Always catch and handle exceptions appropriately
5. Validate inputs: Use Pydantic models for data validation
6. Document your code: Write clear docstrings and comments
7. Review your own code: Do a self-review before requesting reviews

By following this development workflow, you’ll contribute high-quality code to the Definable backend project while maintaining a smooth collaborative process.