Three-Branch Strategy

The three-branch strategy gives upstream changes a controlled path into the fork. Each branch is a checkpoint, so a failure stops at the stage where it happened while synchronization continues.

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: Compose PR body from upstream commit range
        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: Sync Review - Merge the sync PR into fork_upstream
Step 2: Conflict Resolution - Resolve on fork_integration when the cascade merge fails
Step 3: Production Approval - Approve the release PR to main
Step 4: Release - Merge the Release Please PR when the version is ready