Three-Branch Strategy

The three-branch strategy forms the cornerstone of safe, systematic fork management in the OSDU SPI Fork Management system. This architectural pattern provides controlled integration checkpoints that prevent cascade failures while enabling continuous upstream synchronization.

Branch Architecture

graph TD
    A[Upstream Repository] --> B[fork_upstream<br/>Mirror]
    B --> C[fork_integration<br/>Staging]  
    C --> D[main<br/>Production]

    E[Local Development] --> F[Feature Branches]
    F --> D

    style A fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    style B fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style C fill:#fce4ec,stroke:#c2185b,stroke-width:2px
    style D fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    style E fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style F fill:#f3e5f5,stroke:#4a148c,stroke-width:2px

Branch Purposes

Process Flow

Synchronize

sequenceDiagram
    participant U as Upstream Repo
    participant FU as fork_upstream
    participant S as Sync Workflow
    participant SM as Sync State Manager
    participant H as Human Reviewer

    S->>U: Fetch latest changes
    S->>SM: Check existing sync PRs and upstream SHA
    SM->>SM: Compare with stored last-sync state

    alt New upstream changes, no existing PR
        S->>FU: Create new sync branch from fork_upstream
        activate FU
        S->>S: Generate AI analysis
        S->>S: Create new sync PR and issue
        S->>H: Notify human reviewer
    else Upstream advanced, existing PR open
        S->>FU: Update existing sync branch (force push)
        S->>S: Update PR title and description
        S->>S: Add progress comment to existing issue
        S->>H: Update notification on existing issue
    else Duplicate detected (same upstream SHA)
        S->>S: Add reminder comment to existing issue
        S->>H: Gentle reminder notification
    else No changes detected
        S->>S: Exit - no action needed
    end

    opt Human approval received
        H->>H: Review and approve
        H->>FU: Merge sync branch into fork_upstream
        SM->>SM: Update stored sync state
        SM->>SM: Cleanup completed sync artifacts
        deactivate FU
    end

Integrate

sequenceDiagram
    participant M as main
    participant FU as fork_upstream
    participant FI as fork_integration
    participant C as Cascade Workflow
    participant H as Human Reviewer

    C->>M: Check for local changes
    M->>FI: Merge main → fork_integration
    activate FI
    C->>FU: Check for upstream updates
    FU->>FI: Merge fork_upstream → fork_integration
    C->>FI: Run validation suite
    C->>C: Create main PR

    alt Validation Conflicts/Failures
        C->>C: Create conflict resolution issue
        C->>H: Notify about conflicts
        H->>FI: Push conflict resolution to fork_integration
    end

    C->>FI: Run validation suite
    C->>H: Notify human reviewer
    H->>H: Review and approve
    FI->>M: Merge to main
    deactivate FI

Release

sequenceDiagram
    participant M as main
    participant R as Release Workflow
    participant H as Human Reviewer
    participant DR as Downstream Repo

    M->>R: Push to main triggers release
    R->>R: Analyze commits for version bump
    R->>M: Create release branch with CHANGELOG.md
    activate M
    R->>H: Create release PR
    R->>M: Run validation suite
    H->>H: Review and approve
    H->>M: Merge release branch into main
    deactivate M
    R->>R: Create release & tags

    alt Downstream Consumption
        DR->>M: Pull desired release tag
    end

Safety Mechanisms

Branch Protection Rules

Quality Gates

Workflow Benefits

Operational Patterns

Daily Synchronization Cycle

Automated Processing:

Step 1: Check Upstream - Daily automated check for new upstream changes
Step 2: Sync Detection - AI-enhanced analysis of change scope and impact
Step 3: Integration Attempt - Automated merge to integration branch
Step 4: Validation Execution - Comprehensive testing and security scanning

Human Intervention Points:

Step 1: Conflict Resolution - Manual resolution when automated merge fails
Step 2: Validation Review - Assessment of test results and security findings
Step 3: Production Approval - Final authorization for changes to reach main
Step 4: Release Coordination - Alignment with downstream system requirements

Emergency Procedures

Upstream Rollback

If upstream changes cause issues: 1. Identify last known good state in fork_upstream 2. Create rollback branch from previous stable point 3. Update fork_integration with rollback changes 4. Execute normal validation and approval process

Production Hotfix

For urgent Azure SPI fixes: 1. Create hotfix branch from current main 2. Implement and test fix in isolation 3. Fast-track through integration validation 4. Deploy with minimal upstream integration delay