Skip to content

Commit 02b1986

Browse files
authored
docs: Add fork branch strategy documentation (#6)
## Why? The Intercom fork uses a two-branch model that needs documentation so team members understand: - Which branch to use for development (`fork-main`) - How the automated weekly sync works (`main` branch) - The workflow for fast-tracking contributions before upstream acceptance Without this documentation, it's unclear why we have two branches and how to work with them. ## How? Created `FORK.md` that documents: - **Branch model**: `main` (upstream mirror, auto-synced) vs `fork-main` (active development) - **Workflow**: How to add features, sync with upstream, and handle merged PRs - **Rationale**: Why this "fast-track" pattern enables using features immediately while maintaining automated syncs The documentation follows the established pattern from the Intercom monolith's sync workflow and provides practical commands for common operations.
1 parent 8353cb3 commit 02b1986

File tree

2 files changed

+86
-0
lines changed

2 files changed

+86
-0
lines changed

.github/pull_request_template.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# ⚠️ Important: Check Your Base Branch
2+
3+
**This PR should target `fork-main`, not `main`.**
4+
5+
-**`fork-main`** ← Active development branch (use this!)
6+
-**`main`** ← Auto-synced upstream mirror (locked, do not use)
7+
8+
If you accidentally selected `main` as the base branch, change it using the dropdown above before submitting.
9+
10+
---
11+
12+
## Why?
13+
14+
[Brief description of the problem or opportunity this PR addresses]
15+
16+
## How?
17+
18+
[High-level approach and key implementation decisions]
19+
20+
## Test Plan
21+
22+
[How to verify the changes work as expected]
23+
24+
---
25+
26+
📚 **New to this fork?** Read [FORK.md](../FORK.md) to understand our branch strategy.

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)