Synchronisation between internal and external repositories

[FScholPer]

Discussed in https://github.com/orgs/eclipse-score/discussions/1705

^{Originally posted by AlexanderLanin September 5, 2025}

⚠️ Disclaimer: This is a first ChatGPT-generated draft.
Needs scope alignment. Do we want to describe the two-org approach here?

Forking the SCORE Organization: Public & Private Forks

Partners working with SCORE typically need two forks:

1. a public fork to contribute upstream via PRs
2. a private/internal fork to integrate SCORE with company systems (CI/CD, compliance, secrets).

This guide introduces the concept at three levels of detail:

• Executive level: why both forks matter
• Normal level: typical workflows and contribution models
• Implementation level: sync, branches, and protections (only inline comments, no full scripts)

---

1. Executive Level (Why)

• Public forks keep contributions visible and upstreamable.
• Private forks allow integration with proprietary code and internal policies.
• Two contribution models exist:
  • Internal-first (gated): private review before public PR.
  • Public-first (open): direct contribution via public fork.
• Tradeoff: Internal-first = compliance/confidentiality; Public-first = velocity/community collaboration.

---

2. Normal Level (What)

Fork Types

• Public Forks

  • For feature branches and PRs only.
  • Must remain clean and minimal.

• Private/Internal Forks

  • Host mirrored upstream branches (main, release/*).
  • Contain company-specific branches (internal/main, internal/feature/*).
  • Enforce internal CI/CD, CODEOWNERS, and compliance.

Contribution Models

• Internal-first (gated):

  • Flow: dev → internal PR → internal review → promote branch → public fork → upstream PR.
  • Pros: compliance, confidentiality.
  • Cons: slower, more complex.

• Public-first (open):

  • Flow: dev → public fork feature branch → upstream PR.
  • Pros: fast, transparent, community-friendly.
  • Cons: needs guardrails to avoid leaks.

---

3. Implementation Level (How)

Repo Sync

• Initial seed: a one-time full mirror into an empty private repo.
• Ongoing sync: explicitly push upstream branches (e.g., main, release/*) into private fork; avoid overwriting internal/*.
• Avoid git push --mirror except at initial seed or for read-only mirrors.

Branch Layout

• main, release/* → upstream mirrors (bot-only updates).
• internal/* → private company branches.
• feature/* → short-lived public fork branches for upstream PRs.

Protections & Policies

• Public fork:
  • No secrets.
  • Basic lint/format/build/test checks.
• Private fork:
  • Internal CI with compliance/security.
  • Protect upstream branches.
  • Require CODEOWNERS + review on internal/*.

Promotion Flow

• Internal-first:
  • Rebase internal feature branch onto upstream main.
  • Strip internal-only commits/files if needed.
  • Push result into public fork, open PR upstream.

CI Hooks

• Internal PRs: run full secret-backed compliance checks.
• Public PRs: run open CI checks only.
• Optional: trigger internal CI on public PR head (read-only, no secret leaks).

---

TL;DR

• Always keep two forks:
  • Public fork = upstream PRs.
  • Private fork = integration & compliance.
• Choose a contribution model:
  • Internal-first = safer but slower.
  • Public-first = faster but riskier.
• Protect mirrored upstream branches; keep internal work separate.
• Automate syncs, document policies, and define responsibilities.