orion/docs/development/contributing.md

Contributing Guide

Thank you for contributing to the Wizamart platform! This guide will help you get started.

Getting Started

Prerequisites

• Python 3.11 or higher
• Git
• Virtual environment tool (venv)

Initial Setup

1. Clone the repository:

git clone <repository-url>
cd letzshop-product-import

2. Create and activate virtual environment:

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

3. Install all dependencies:

make install-all

4. Set up the database:

make db-setup

Development Workflow

1. Create a Feature Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

2. Make Your Changes

Follow our Code Quality guidelines:

# Format and lint your code
make check

# Run tests
make test-fast

3. Write Tests

• Add tests for new features
• Update tests for changed functionality
• Maintain or improve code coverage

# Run tests with coverage
make test-coverage

4. Commit Your Changes

Use clear, descriptive commit messages:

git add .
git commit -m "feat: add user profile endpoint"
# or
git commit -m "fix: resolve authentication token expiry issue"

Commit message format:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• style: - Code formatting (no functional changes)
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

5. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a pull request on GitHub.

Code Quality Standards

We use modern tooling to maintain high code quality. See Code Quality Guide for details.

Before Committing

Always run:

make check

This will:

1. Format your code with Ruff
2. Lint and auto-fix issues
3. Run type checking with mypy

Pre-Commit Checklist

• Code is formatted (make format)
• All linting issues resolved (make lint)
• Tests pass (make test)
• Coverage hasn't decreased
• Documentation updated if needed
• Commit message is clear and follows format

Testing Guidelines

Test Structure

tests/
 unit/              # Unit tests (fast, isolated)
 integration/       # Integration tests (slower, multiple components)
 performance/       # Performance tests
 system/           # End-to-end system tests

Writing Tests

import pytest
from app.services.user_service import UserService

class TestUserService:
    """Test suite for UserService"""

    def test_create_user(self, db):
        """Test user creation"""
        service = UserService(db)
        user = service.create_user("test@example.com", "password123")

        assert user.email == "test@example.com"
        assert user.id is not None

Running Tests

# All tests
make test

# Only unit tests
make test-unit

# Only integration tests
make test-integration

# With coverage
make test-coverage

# Fast tests only (skip slow ones)
make test-fast

Documentation

Writing Documentation

Documentation is written in Markdown and built with MkDocs.

1. Add/update documentation in docs/ directory
2. Build and check documentation:

make docs-build

3. Preview documentation locally:

make docs-serve

Then visit http://localhost:8001

Documentation Structure

Follow the existing structure in mkdocs.yml:

• Getting Started - Installation, setup, configuration
• Architecture - System design and patterns
• API Documentation - API reference for consumers
• Backend Development - Backend development guides
• Frontend Development - Frontend development guides
• Development - General development resources
• Testing - Testing guides and practices
• Deployment - Deployment and operations
• Features - Feature-specific documentation
• User Guides - End-user documentation

Database Changes

Creating Migrations

make migrate-create message="description of changes"

Migration Guidelines

1. Always review generated migrations
2. Test migrations both up and down
3. Don't modify existing migrations that have been deployed
4. Use descriptive names for migrations
5. Include reversibility when possible

# Apply migrations
make migrate-up

# Rollback last migration
make migrate-down

# Check migration status
make migrate-status

Code Style Guidelines

Python Style

We follow PEP 8 with some modifications:

• Line length: 88 characters (black default)
• Quotes: Double quotes for strings
• Imports: Organized by Ruff (isort rules)
• Type hints: Encouraged but not required

Naming Conventions

• Functions/methods: snake_case
• Classes: PascalCase
• Constants: UPPER_CASE
• Private methods: _leading_underscore
• Modules: snake_case.py

See Naming Conventions for more details.

Import Organization

Imports are automatically organized by Ruff into sections:

# Future imports
from __future__ import annotations

# Standard library
import logging
from datetime import datetime

# Third-party
from fastapi import Depends
from sqlalchemy.orm import Session

# First-party
from app.core.database import get_db
from models.database.user import User

# Local
from .dependencies import get_current_user

Architecture Guidelines

Service Layer Pattern

Business logic belongs in services:

# Good
class UserService:
    def create_user(self, email: str, password: str) -> User:
        # Business logic here
        pass

# Bad - business logic in endpoint
@router.post("/users")
def create_user(email: str, password: str):
    # Don't put business logic here
    pass

Dependency Injection

Use FastAPI's dependency injection:

from fastapi import Depends

@router.get("/users/me")
def get_current_user(
    user: User = Depends(get_current_user_from_token)
):
    return user

Error Handling

Use custom exceptions:

from app.exceptions import UserNotFoundException

def get_user(user_id: int) -> User:
    user = db.query(User).get(user_id)
    if not user:
        raise UserNotFoundException(user_id)
    return user

Common Tasks

Adding a New Endpoint

1. Define route in app/api/v1/{context}/{resource}.py
2. Create/update service in app/services/{resource}_service.py
3. Add schema models in models/schema/{resource}.py
4. Write tests in tests/integration/api/v1/test_{resource}_endpoints.py
5. Update documentation

Adding a New Feature

1. Create feature branch
2. Design database schema (if needed)
3. Create migration (if needed)
4. Implement backend logic
5. Add tests (unit + integration)
6. Update documentation
7. Create pull request

Debugging

# Start development server with auto-reload
make dev

# Check logs
tail -f logs/app.log

# Run specific test
pytest tests/path/to/test.py::test_function_name -v

Getting Help

• Documentation: Check the docs
• Issues: Search existing issues or create a new one
• Questions: Use GitHub Discussions

Pull Request Process

1. Create PR with clear title and description
2. Link related issues using "Fixes #123" or "Relates to #456"
3. Wait for review - maintainers will review your code
4. Address feedback - make requested changes
5. Merge - once approved, your PR will be merged

PR Checklist

• Tests pass (make test)
• Code is formatted (make check)
• Documentation updated
• Commit messages follow format
• No merge conflicts
• PR description explains changes

Code Review Guidelines

As a Reviewer

• Be respectful and constructive
• Focus on code, not the person
• Explain the "why" behind suggestions
• Approve when ready, request changes if needed

As a Contributor

• Be open to feedback
• Ask questions if unclear
• Make requested changes promptly
• Thank reviewers for their time

Additional Resources

• Code Quality Guide
• Testing Guide
• Database Migrations
• Architecture Overview
• Naming Conventions

License

By contributing, you agree that your contributions will be licensed under the same license as the project.