|
| 1 | +# Intercom Fork - Branch Strategy |
| 2 | + |
| 3 | +This is an Intercom fork of [open-telemetry/opentelemetry-ruby-contrib](https://github.com/open-telemetry/opentelemetry-ruby-contrib). |
| 4 | + |
| 5 | +## Branch Model |
| 6 | + |
| 7 | +We maintain two main branches: |
| 8 | + |
| 9 | +### `main` - Upstream Mirror |
| 10 | +- **Purpose**: Clean mirror of the upstream `open-telemetry/opentelemetry-ruby-contrib` main branch |
| 11 | +- **Updates**: Automatically synced weekly via GitHub Actions ([workflow](https://github.com/intercom/intercom/blob/master/.github/workflows/sync-org-forks.yml)) |
| 12 | +- **Policy**: Never commit directly to this branch. It should always fast-forward to match upstream. |
| 13 | + |
| 14 | +### `fork-main` - Active Development Branch |
| 15 | +- **Purpose**: Contains Intercom-specific changes and contributions pending upstream acceptance |
| 16 | +- **Usage**: This is the branch referenced in the Intercom monolith's Gemfile |
| 17 | +- **Updates**: Periodically merge `main` into `fork-main` to pull in upstream changes |
| 18 | + |
| 19 | +## Workflow |
| 20 | + |
| 21 | +### Adding New Features or Fixes |
| 22 | + |
| 23 | +1. **Create PR to upstream**: Submit your changes to `open-telemetry/opentelemetry-ruby-contrib` |
| 24 | +2. **Fast-track in fork**: Add the same changes to `fork-main` so Intercom can use them immediately |
| 25 | +3. **When upstream merges**: |
| 26 | + - The weekly sync automatically pulls changes into `main` |
| 27 | + - Merge `main` into `fork-main` to reconcile |
| 28 | + - Your commit from step 2 stays in history, but the upstream version becomes canonical |
| 29 | + |
| 30 | +### Syncing with Upstream |
| 31 | + |
| 32 | +```bash |
| 33 | +# Fetch latest from both branches |
| 34 | +git fetch origin main fork-main |
| 35 | + |
| 36 | +# Merge upstream changes into fork-main |
| 37 | +git checkout fork-main |
| 38 | +git merge origin/main |
| 39 | + |
| 40 | +# Push the merged changes |
| 41 | +git push origin fork-main |
| 42 | +``` |
| 43 | + |
| 44 | +### When Upstream Accepts Your PR |
| 45 | + |
| 46 | +Once your PR is merged upstream and synced to `main`, the changes exist in both branches. You can optionally: |
| 47 | +- Keep the merge commit history as-is (simplest) |
| 48 | +- Rebase `fork-main` to remove redundant commits (advanced, requires force-push) |
| 49 | + |
| 50 | +## Why This Model? |
| 51 | + |
| 52 | +This "fast-track" pattern allows us to: |
| 53 | +- ✅ Use features immediately without waiting for upstream review cycles |
| 54 | +- ✅ Maintain automated weekly syncs (no divergence issues) |
| 55 | +- ✅ Contribute back to open source (all changes are intended for upstream) |
| 56 | +- ✅ Keep clear separation between upstream mirror and active development |
| 57 | + |
| 58 | +## Questions? |
| 59 | + |
| 60 | +For questions about this fork or the branch strategy, ask in #builder-tools or consult the [sync workflow documentation](https://github.com/intercom/intercom/blob/master/.github/workflows/sync-org-forks.md). |
0 commit comments