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/>Filtered Shared Code]
    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 F as Upstream Filter
    participant H as Human Reviewer

    S->>U: Fetch latest changes
    S->>S: Check existing sync PRs and upstream SHA
    S->>F: Generate and verify provider-less tree

    alt New upstream changes, no existing PR
        S->>FU: Create sync branch containing generated tree
        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: Keep existing PR and issue unchanged
    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
        S->>S: Update issue and PR state
        S->>S: 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: Assert Azure trees and stamp POM versions
    C->>FI: Build and test core,azure
    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

A downstream repository does not have to stop at pulling release tags. It can be a customer-tier fork running this same three-branch machinery in mirror mode: fork_upstream becomes a verbatim mirror of this repository's main, the cascade integrates it with the downstream's local work, and contribution PRs flow back through the fork network. See Fork Tiers and ADR-039.

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: Filter Transform - Regenerate and verify the upstream-owned tree Step 3: Sync Review - Review and merge the filtered PR to fork_upstream Step 4: Cascade - Merge into integration, stamp Azure POMs, and run validation

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