Skip to content

Commit 5790bbf

Browse files
committed
docs: Add Intercom fork branch strategy documentation
Documents the two-branch model used in the Intercom fork: - main: Clean upstream mirror (auto-synced weekly) - fork-main: Active development with pending upstream contributions Explains the fast-track workflow for using features before upstream acceptance while maintaining automated sync capabilities.
1 parent 8353cb3 commit 5790bbf

File tree

1 file changed

+60
-0
lines changed

1 file changed

+60
-0
lines changed

FORK.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
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

Comments
 (0)