orion/docs/development/contributing.md

# Contributing Guide

Thank you for contributing to the Orion 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:
```bash
git clone <repository-url>
cd letzshop-product-import
```

2. Create and activate virtual environment:
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install all dependencies:
```bash
make install-all
```

4. Set up the database:
```bash
make db-setup
```

## Development Workflow

### 1. Create a Feature Branch

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

### 2. Make Your Changes

Follow our [Code Quality](code-quality.md) guidelines:

```bash
# 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

```bash
# Run tests with coverage
make test-coverage
```

### 4. Commit Your Changes

Use clear, descriptive commit messages:

```bash
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

```bash
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](code-quality.md) for details.

### Before Committing

Always run:

```bash
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

```python
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

```bash
# 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:

```bash
make docs-build
```

3. Preview documentation locally:

```bash
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

```bash
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

```bash
# 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](naming-conventions.md) for more details.

### Import Organization

Imports are automatically organized by Ruff into sections:

```python
# 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:

```python
# 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:

```python
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:

```python
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

```bash
# 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](../index.md)
- **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](code-quality.md)
- [Testing Guide](../testing/testing-guide.md)
- [Database Migrations](migration/database-migrations.md)
- [Architecture Overview](../architecture/overview.md)
- [Naming Conventions](naming-conventions.md)

## License

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