Status

Table of Contents

Developer Workflows

Developer workflows guide contributors and users through common development tasks, from initial setup to advanced debugging techniques.

Categories

Local Development

Setting up and running the Blueberry IDP locally.

  • Environment Setup - Install dependencies and tools
  • Docker Compose Workflow - Run services locally
  • Configuration Management - Local config setup
  • Hot Reload Development - Live code updates
  • Local Testing - Run tests in containers

Testing

Comprehensive testing strategies and procedures.

  • Unit Testing - Test individual components
  • Integration Testing - Test service interactions
  • End-to-End Testing - Full workflow validation
  • Performance Testing - Load and stress tests
  • Security Testing - Vulnerability scanning

Debugging

Troubleshooting techniques and tools.

  • Log Analysis - Finding issues in logs
  • Remote Debugging - Debug running environments
  • Performance Profiling - Identify bottlenecks
  • Network Debugging - Trace API calls
  • Kubernetes Debugging - Pod and service issues

Onboarding

Getting started with the platform.

  • Repository Setup - Clone and configure
  • First Environment - Create your first env
  • Development Workflow - PR to deployment
  • Best Practices - Code standards
  • Contributing Guide - How to contribute

Development Environment

Required Tools

  • Docker - Container runtime
  • Docker Compose - Multi-container apps
  • Python 3.11+ - Backend development
  • Node.js 18+ - Frontend tooling
  • kubectl - Kubernetes CLI
  • gcloud - Google Cloud SDK
  • VS Code - IDE with extensions
  • Postman - API testing
  • k9s - Kubernetes TUI
  • stern - Multi-pod log tailing
  • HTTPie - CLI HTTP client

Common Developer Tasks

Daily Workflow

  1. Pull latest changes
  2. Start local environment
  3. Make code changes
  4. Run tests locally
  5. Create pull request

Testing Workflow

# Run all tests
make test

# Run specific test
docker exec blueberry pytest tests/unit/test_api.py

# Run with coverage
make test-coverage

# Run integration tests
make test-integration

Debugging Workflow

# View logs
docker compose logs -f blueberry

# Enter container shell
docker exec -it blueberry /bin/bash

# Port forward to pod
kubectl port-forward svc/blueberry 8080:80

# Debug Python code
docker exec -it blueberry python -m pdb blueberry/app.py

Development Best Practices

Code Quality

  • Follow PEP 8 for Python
  • Use type hints
  • Write comprehensive tests
  • Document complex logic
  • Regular code reviews

Git Workflow

  • Feature branches
  • Descriptive commits
  • Small, focused PRs
  • Rebase before merge
  • Clean commit history

Testing Strategy

  • Test-driven development
  • High test coverage
  • Mock external services
  • Test error cases
  • Performance benchmarks

Documentation

  • Update docs with code
  • Include examples
  • Document gotchas
  • Keep README current
  • Add inline comments

Local Development Setup

Quick Start

# Clone repository
git clone https://gitlab.com/your-org/blueberry.git
cd blueberry

# Copy environment file
cp .env.example .env

# Start services
docker compose up --build -d

# Run tests
make test

# Access UI
open http://localhost:8080

Configuration

  1. Set up Firebase credentials
  2. Configure GCP project
  3. Set environment variables
  4. Initialize database
  5. Load test data

Troubleshooting

Common Issues

  • Port conflicts - Change ports in docker-compose.yml
  • Memory issues - Increase Docker memory
  • Permission errors - Check file ownership
  • Network issues - Reset Docker network
  • Build failures - Clear Docker cache

Getting Help

  • Check existing issues
  • Search documentation
  • Ask in Slack channel
  • Create detailed bug report
  • Include reproduction steps
Document ID: workflows/developer/README