Development Workflow

This guide covers the step-by-step development process for contributing to the CLOE Toolbox.

Branch Strategy

We follow a feature branch workflow optimized for Azure DevOps:

graph LR
    A[main] --> B[feature/add-new-tool]
    B --> C[Initial setup]
    C --> D[Add core functionality]
    D --> E[Add tests]
    E --> F[Update docs]
    F --> G[merge to main]
    G --> H[Released v1.1.0]

Repository Setup Process

1. Plan Your Contribution

   • Create a feature/user story in Azure DevOps board
   • Define clear acceptance criteria and scope

2. Repository Setup (for new packages)

   • Contact Product Management for repository creation
   • Repository will be pre-configured with:
     • CI/CD Azure Pipelines
     • SonarCloud integration
     • Branch protection policies
     • Required PR settings

3. Local Development Setup

   # Clone repository
   git clone <repository-url>
   cd <repository-name>
   
   # Create and activate environment with uv
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
   # Install dependencies
   uv pip install -e .
   

4. Use Package Templates

   • Refer to Building Blocks for available templates
   • Templates include:
     • Project structure
     • CI/CD configurations
     • Testing frameworks
     • Documentation templates

Step-by-Step Development Process

1. Create Feature Branch

   # Create and switch to feature branch
   git checkout -b feature/your-feature-name
   
   # Link to Azure DevOps work item
   git commit -m "feat: initial setup for feature #1234"
   

2. Develop Your Feature

   • Follow the coding standards and guidelines in our Python guide
   • Use appropriate building blocks to avoid redundant development
   • Implement features incrementally with regular commits

3. Write Comprehensive Tests

   • Use pytest for Python projects
   • Aim for >80% code coverage
   • Include unit, integration, and end-to-end tests
   • Place tests in the tests/ folder

4. Update Documentation

   • Document new features in the docs/ folder
   • Update API documentation
   • Add usage examples and tutorials
   • Follow our documentation guide

5. Commit Changes with Conventional Commits

   We use Conventional Commits for clear commit history:

   # Feature commits
   git commit -m "feat: add user authentication module #1234"
   
   # Bug fixes
   git commit -m "fix: resolve memory leak in data processor #1234"
   
   # Documentation
   git commit -m "docs: add API reference for new endpoints #1234"
   

   Work Item Linking

   Always include the Azure DevOps work item ID (e.g., #1234) to automatically link commits to your user story or task.

6. Create Pull Request

   • Push your branch to Azure DevOps
   • Create a detailed PR description including:
     • Summary of changes
     • Testing performed
     • Breaking changes (if any)
     • Screenshots/demos (if applicable)

7. Code Review & Deployment

   • Address reviewer feedback promptly
   • Ensure CI/CD pipeline passes
   • Once approved, PR will be merged automatically
   • Monitor deployment to ensure successful release