Introduction

This guide describes the structured branching model used to integrate GIMP development updates into the Artbox project.

Contents

• Updating Artbox to GIMP Dev
  • Staged Construction Process
  • Key Benefits
  • Build Control
• Staged Branch Organization
  • Stage Management
  • Conflict Resolution
• Notes

Branch Development Flow for GIMP to Artbox

The development process follows a staged pipeline architecture where the GIMP development branch serves as the foundation. Branches are organized into numbered stages that build upon each other, with each stage creating a checkpoint branch (common-XX) that serves as the foundation for the next stage. The final artbox branch represents the integrated work from all stages.

Updating Artbox to GIMP Dev

Artbox uses a staged build pipeline to integrate GIMP development updates and branches. The process creates numbered checkpoint branches (common-00, common-01, etc.) that build upon each other to produce the final artbox branch.

Staged Construction Process

The build pipeline follows this flow:

GIMP Source → common-00 → common-01 → common-02 → ... → common-06 → artbox

Each stage processes a specific group of branches:

1. Stage Setup: Clone the previous stage’s output branch
2. Branch Integration: Cherry-pick commits from assigned branches
3. Checkpoint Creation: Merge processed branches and create a single squashed commit
4. Pipeline Progression: Each stage builds on the previous stage’s output

Key Benefits

• Modular Updates: Individual stages can be rebuilt without affecting the entire pipeline
• Conflict Isolation: Issues are contained within specific stages for easier resolution
• Reproducible Builds: Each stage creates a clean checkpoint for consistent results
• Flexible Rebuilds: Partial pipeline reconstruction allows targeted updates

Build Control

The construction process can be controlled at multiple levels:

• Full Rebuild: Process all stages from GIMP source to final artbox branch
• Partial Rebuild: Update only specific stages and downstream dependencies
• Stage-by-Stage: Enable or disable individual stages as needed

Staged Branch Organization

All branches are organized into numbered stages to ensure conflict-free construction. The system focuses on ordering branches so that dependencies are resolved correctly and conflicts are minimized.

Stage Management

Stages provide flexible organization of branches:

• Conflict Prevention: Branches within the same stage are designed to work together without conflicts
• Dependency Ordering: Earlier stages prepare the foundation for later stages
• Flexible Assignment: Branches can be moved between stages as requirements change
• Dynamic Expansion: New stages can be inserted or appended as the project grows

Conflict Resolution

The staged approach simplifies conflict management:

• Stage-Level Isolation: Issues are contained within specific stages
• Clear Dependencies: Each stage builds on well-defined checkpoint branches
• Selective Rebuilds: Problem stages can be reconstructed without affecting the entire pipeline
• Branch Reorganization: Conflicting branches can be moved to different stages to resolve issues

When conflicts occur during pipeline construction, they can be resolved by:

• Moving problematic branches to later stages
• Inserting new intermediate stages to separate conflicting changes
• Reordering branches within stages to optimize integration

Notes

The staged pipeline architecture provides flexible stage organization:

• Unified Branch Management: All branches are treated equally and organized purely by integration requirements
• Dynamic Reorganization: Branches can be moved between stages to optimize the build process
• Scalable Architecture: New stages can be easily inserted or appended to accommodate project growth
• Conflict-Driven Organization: Stage assignments are based on preventing conflicts rather than branch functionality

This approach provides maximum flexibility for managing complex integrations while maintaining a clean, reproducible build process.