Skip to content

Developer Workflow

This guide outlines the recommended workflow and best engineering practices.

Table of Contents

Getting Started

Prerequisites

Initial Setup

# Clone the repository
git clone https://github.com/Orbital-Kitchens/orbital-manager-backend.git
cd orbital-manager-backend

# Verify Pants installation
pants --version

# Install dependencies (handled by Pants)
pants test ::  # This will also bootstrap dependencies

Development Workflow

1. Create a Feature Branch

# Update main branch
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/your-feature-name

2. Read Context Documentation

Before writing any code, always read the .agents/ directories for context:

  • Start with .agents/index.md (root directory)
  • Read service-specific docs: <service>/.agents/index.md
  • Check shared components: shared/.agents/index.md

This provides essential context and prevents unnecessary token usage.

3. Write Code

Follow these principles:

  • Google Python Style Guide: All code must follow Google's Python style conventions
  • Type Hints: Mandatory for all functions and methods
  • Docstrings: Required for all functions, classes, and modules (Google-style)
  • Keep Functions Small: Aim for functions under 20 lines
  • Cyclomatic Complexity: Keep complexity under 10

4. Run Code Quality Checks

# Check for linting issues
ruff check .

# Auto-fix linting issues where possible
ruff check . --fix

# Check formatting
ruff format --check .

# Apply formatting
ruff format .

5. Run Tests

# Run all tests
pants test ::

# Run tests for specific service
pants test order_management_service/tests/

# Run specific test file
pants test order_management_service/tests/test_mongo_listener.py

# Run specific test with detailed output
pants test order_management_service/tests/test_mongo_listener.py::TestMongoListener::test_initialization --test-output=all

6. Commit Changes

# Stage your changes
git add <files>

# Commit with descriptive message
git commit -m "Add feature: brief description

7. Push and Create PR

# Push to remote
git push origin feature/your-feature-name

# Create PR using GitHub CLI (optional)
gh pr create --title "Feature: Your feature name" --body "Description of changes"

Code Quality Standards

Ruff Configuration

Ruff is used for both linting and formatting. Configuration is in pyproject.toml or ruff.toml.

Common Ruff Commands:

# Show statistics
ruff check . --statistics

# Show only errors (concise)
ruff check . --output-format=concise

# Fix all auto-fixable issues
ruff check . --fix

# Format all files
ruff format .

Style Guidelines

  1. Naming Conventions

  2. Functions/variables: snake_case

  3. Classes: PascalCase
  4. Constants: UPPER_SNAKE_CASE
  5. Docstrings (Google Style)

def calculate_total(items: list[Item], discount: float = 0.0) -> float:
    """Calculate the total price of items with optional discount.

    Args:
        items: List of items to calculate total for.
        discount: Discount percentage (0.0 to 1.0).

    Returns:
        Total price after discount.

    Raises:
        ValueError: If discount is outside valid range.
    """
    pass
3. Type Hints

from typing import Optional, Union

def process_order(
    order_id: str,
    items: list[dict[str, any]],
    user_id: Optional[str] = None
) -> dict[str, any]:
    """Process an order with given items."""
    pass

Generated Files - DO NOT EDIT

Never edit these auto-generated files:

  • *_pb2.py (Protocol Buffer generated)
  • *_pb2_grpc.py (gRPC generated)
  • *_pb2.pyi (Type stubs)

To modify these, edit the corresponding .proto files and rebuild.

Code Comments and TODOs

TODO Format

All TODO comments in the codebase must follow this standardized format:

# TODO [ORB-123]: Brief description of what needs to be done

Format Requirements:

  • Use //TODO for language-specific comment syntax (e.g., JavaScript, TypeScript)
  • Use # TODO for Python
  • Include the ticket number in square brackets: [ORB-XXX]
  • Follow with a colon and a brief description
  • Keep descriptions concise but actionable

Examples

Python:

def process_order(order_id: str) -> dict[str, any]:
    """Process an order."""
    # TODO [ORB-456]: Add validation for order_id format
    # TODO [ORB-457]: Implement retry logic for failed payments

    result = {"status": "pending"}
    return result

JavaScript/TypeScript:

function calculateDiscount(price, userTier) {
    // TODO [ORB-789]: Implement tiered discount logic
    return price * 0.9;
}

Proto files:

message Order {
    string order_id = 1;
    // TODO [ORB-234]: Add timestamp field for order creation
}

When to Use TODOs

Use TODO comments for:

  • Technical Debt: Code that works but needs improvement
  • Future Features: Planned enhancements not in current scope
  • Known Limitations: Edge cases not yet handled
  • Performance Optimizations: Areas identified for optimization
  • Refactoring: Code that should be restructured later

When NOT to Use TODOs

Don't use TODOs for:

  • Critical Bugs: Create a ticket and fix immediately
  • Security Issues: Fix before merging
  • Broken Functionality: Fix before committing
  • Vague Ideas: Document in .agents/ or architecture docs instead

TODO Tracking

  • All TODOs must reference a valid Orbital ticket (ORB-XXX)
  • Create the ticket before adding the TODO if it doesn't exist
  • TODOs should be reviewed during code reviews
  • Periodically audit TODOs and convert to tickets or remove if obsolete

Bad Examples

# TODO: fix this later  ❌ (no ticket, vague)
# TODO [ORB-123] implement caching  ❌ (missing colon)
# TODO implement proper error handling  ❌ (no ticket)
# Fix this weird bug  ❌ (not a TODO format, should be fixed now)

Good Examples

# TODO [ORB-123]: Implement Redis caching for frequently accessed orders  ✓
# TODO [ORB-456]: Add rate limiting to prevent API abuse  ✓
# TODO [ORB-789]: Refactor this function to reduce cyclomatic complexity  ✓

Testing

Test Organization

Tests are organized by service:

  • order_management_service/tests/
  • kitchen_batch_tool_service/tests/
  • shared/tests/

Writing Tests

import pytest
from your_module import your_function


class TestYourFeature:
    """Tests for your feature."""

    def test_basic_functionality(self) -> None:
        """Test basic functionality works as expected."""
        result = your_function("input")
        assert result == "expected_output"

    def test_edge_case(self) -> None:
        """Test edge case handling."""
        with pytest.raises(ValueError):
            your_function(None)

Running Tests

# All tests
pants test ::

# With coverage
pants test :: --coverage

# Specific test with full output
pants test path/to/test.py --test-output=all

Pull Request Process

Orbital Pre-Commit Quality Checks

Before creating a PR, run these checks:

ruff check .        # Linting
ruff format .       # Formatting
pants test ::       # All tests

Before Creating a PR

  • All tests pass: pants test ::
  • Code is formatted: ruff format .
  • Linting passes: ruff check .
  • Documentation updated (if needed)
  • Docstrings added for new functions/classes
  • Type hints added
  • Never edited generated files: *_pb2.py, *_pb2_grpc.py, *_pb2.pyi

Orbital Coding Standards Checklist

When writing code, ensure:

  • Follow Google Python Style Guide
  • Add type hints to all functions and methods
  • Write Google-style docstrings for all functions, classes, and modules
  • Keep functions focused and under 20 lines
  • Keep cyclomatic complexity under 10
  • Use Orbital TODO format: # TODO [ORB-XXX]: Description

PR Description Template

This is not a strict guidline on PR description

## Summary
Brief description of what this PR does.

## Changes
- List of specific changes made
- Another change

## Testing
How was this tested?

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Ruff checks pass
- [ ] Type hints added
- [ ] Docstrings added
- [ ] Add description or screenshots of the changes if neeeded

Review Process

  1. Create PR with descriptive title and body
  2. Address review comments
  3. Wait for CI/CD pipeline to pass
  4. Get approval from at least one team member
  5. Merge to main

See Code Reviews for detailed PR guidelines.

CI/CD Pipeline

Automated Checks

On every push and PR, the CI pipeline runs:

  • Ruff linting checks
  • Ruff formatting checks
  • Full test suite via Pants
  • Type checking

GitHub Actions Workflows

  • CI Pipeline (.github/workflows/ci.yml): Runs on all PRs

Best Practices

Security

  • Never commit secrets or credentials
  • Use environment variables for sensitive data
  • Review .gitignore before committing new file types

Performance

  • Profile code before optimizing
  • Use appropriate data structures
  • Consider async operations for I/O-bound tasks

Documentation

  • Keep .agents/ documentation up to date
  • Document complex business logic
  • Add comments for non-obvious code
  • Update this workflow guide as processes evolve

Git Hygiene

  • Write descriptive commit messages
  • Keep commits atomic (one logical change per commit)
  • Rebase feature branches on main regularly
  • Don't force push to shared branches

Troubleshooting

Common Issues

Pants build fails:

# Clear Pants cache
rm -rf .pants.d
pants --version

Ruff conflicts:

# Reset formatting
ruff format .
ruff check . --fix

Tests fail locally but pass in CI:

  • Check Python version matches CI
  • Verify all dependencies are installed
  • Check for environment-specific issues

Resources

Getting Help

  • Check .agents/ directories for service-specific documentation
  • Ask in team chat or create a GitHub issue

Last Updated: 2025-10-23