Skip to content

Commit 5d1242b

Browse files
deepakdgupta1deepakdgupta1
committed
feat: Add fork workflow strategy documentation and update upstream sync to auto-push clean merges directly to the target branch, only creating pull requests for conflicts.
1 parent 7a1a0de commit 5d1242b

3 files changed

Lines changed: 112 additions & 17 deletions

File tree

‎.github/workflows/upstream-sync.yml‎

Lines changed: 11 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,12 @@ jobs:
7272
run: |
7373
git push -f origin "$SYNC_BRANCH"
7474
75+
- name: Push to Target (Auto-Merge)
76+
if: steps.merge.outputs.merge_status == 'success'
77+
run: |
78+
git push origin "$SYNC_BRANCH:$TARGET_BRANCH"
79+
echo "Successfully synced to $TARGET_BRANCH"
80+
7581
- name: Ensure Labels Exist
7682
env:
7783
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -84,22 +90,16 @@ jobs:
8490
gh label list --repo ${{ github.repository }}
8591
8692
- name: Create Pull Request
87-
if: steps.merge.outputs.merge_status == 'success' || steps.merge.outputs.merge_status == 'conflict'
93+
if: steps.merge.outputs.merge_status == 'conflict'
8894
run: |
8995
# Check if PR already exists
9096
existing_pr=$(gh pr list --repo ${{ github.repository }} --head "$SYNC_BRANCH" --base "$TARGET_BRANCH" --json number -q '.[0].number')
9197
9298
if [[ -z "$existing_pr" ]]; then
9399
echo "Creating new PR..."
94-
if [[ "${{ steps.merge.outputs.merge_status }}" == "conflict" ]]; then
95-
TITLE="⚠️ Upstream Sync (Conflicts Detected)"
96-
BODY="This PR syncs changes from upstream. **Conflicts were detected and committed with markers.** Please review and resolve them."
97-
LABELS="upstream-sync,conflict"
98-
else
99-
TITLE="🔄 Upstream Sync (Clean)"
100-
BODY="This PR syncs changes from upstream. No conflicts detected."
101-
LABELS="upstream-sync"
102-
fi
100+
TITLE="⚠️ Upstream Sync (Conflicts Detected)"
101+
BODY="This PR syncs changes from upstream. **Conflicts were detected and committed with markers.** Please review and resolve them."
102+
LABELS="upstream-sync,conflict"
103103
104104
PR_URL=$(gh pr create \
105105
--repo ${{ github.repository }} \
@@ -115,11 +115,7 @@ jobs:
115115
echo "PR_URL=https://github.com/${{ github.repository }}/pull/$existing_pr" >> "$GITHUB_ENV"
116116
117117
# Update comments/labels if status changed
118-
if [[ "${{ steps.merge.outputs.merge_status }}" == "conflict" ]]; then
119-
gh pr edit "$existing_pr" --repo ${{ github.repository }} --title "⚠️ Upstream Sync (Conflicts Detected)" --add-label "conflict" --body "Updates from upstream. Conflicts detected."
120-
else
121-
gh pr edit "$existing_pr" --repo ${{ github.repository }} --title "🔄 Upstream Sync (Clean)" --remove-label "conflict" --body "Updates from upstream. Clean merge."
122-
fi
118+
gh pr edit "$existing_pr" --repo ${{ github.repository }} --title "⚠️ Upstream Sync (Conflicts Detected)" --add-label "conflict" --body "Updates from upstream. Conflicts detected."
123119
fi
124120
125121
- name: Analyze Conflicts with AI

‎docs/fork-workflow-strategy.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Fork Workflow Strategy: "The Integration Branch Pattern"
2+
3+
This guide outlines the optimal workflow for maintaining a long-lived fork that consumes upstream updates while developing local features.
4+
5+
## The Goal
6+
1. **Consume Upstream**: Get daily updates from `Dicklesworthstone/agentic_coding_flywheel_setup`.
7+
2. **Develop Locally**: Build new features in isolation.
8+
3. **Integrate**: Combine both sources into a stable deployment branch.
9+
10+
## The "Integration Branch" Pattern
11+
12+
We use a specific branching strategy to keep streams of work clean.
13+
14+
### Branches
15+
16+
| Branch Name | Role | Source of Truth |
17+
| :--- | :--- | :--- |
18+
| `main` | **Pure Upstream Mirror** | ONLY upstream code. Never commit here directly. |
19+
| `feature/*` | **Your Work** | Your isolated feature development. |
20+
| `local-desktop-installation-support` | **Integration / Deployment** | The "Production" branch for your local install. Contains Upstream + Your Features. |
21+
22+
### Visual Data Flow
23+
24+
```mermaid
25+
graph TD
26+
subgraph Upstream Repo
27+
U[Upstream / main]
28+
end
29+
30+
subgraph Your Fork
31+
M[main<br/>(Pure Copy)]
32+
F1[feature/my-cool-config]
33+
F2[feature/custom-scripts]
34+
I[local-desktop-installation-support<br/>(Integration Branch)]
35+
end
36+
37+
%% Flows
38+
U -->|Action: Daily Sync| I
39+
F1 -->|PR: Merge| I
40+
F2 -->|PR: Merge| I
41+
42+
style I fill:#d4edda,stroke:#28a745,stroke-width:2px
43+
style U fill:#cce5ff,stroke:#004085,stroke-width:2px
44+
```
45+
46+
## Daily Protocol
47+
48+
### 1. The Automated Morning Sync
49+
Your GitHub Action `upstream-sync.yml` runs daily.
50+
- It pulls `upstream/main`.
51+
- It attempts to merge into `local-desktop-installation-support`.
52+
- **If Clean**: It pushes automatically. You wake up to a fresh, up-to-date repo.
53+
- **If Conflict**: It opens a PR with conflict markers. You must resolve it (see [Upstream Sync Guide](./upstream-sync.md)).
54+
55+
### 2. Developing a New Feature (The "Right Way")
56+
57+
**NEVER** work directly on `local-desktop-installation-support`. Always use a feature branch.
58+
59+
#### Step 1: Start Fresh
60+
Always branch off the latest integration branch.
61+
```bash
62+
git checkout local-desktop-installation-support
63+
git pull origin local-desktop-installation-support
64+
git checkout -b feature/my-new-idea
65+
```
66+
67+
#### Step 2: Hack & Commit
68+
Work as usual.
69+
```bash
70+
# code code code
71+
git add .
72+
git commit -m "Add my new idea"
73+
```
74+
75+
#### Step 3: Merge back to Integration
76+
When ready, merge your feature into the integration branch.
77+
```bash
78+
git checkout local-desktop-installation-support
79+
git merge feature/my-new-idea
80+
git push origin local-desktop-installation-support
81+
```
82+
*Tip: If you want to use PRs for your own features to run tests, that's even better! Open a PR from `feature/my-new-idea` -> `local-desktop-installation-support`.*
83+
84+
### 3. Handling Upstream "Gotchas"
85+
86+
Sometimes upstream changes a file you also changed.
87+
88+
1. **The Action fails to merge cleanly.**
89+
2. **You get a Notification.**
90+
3. **You Open the PR** created by the action.
91+
4. **You Resolve Conflicts** (locally or in UI) to decide: "Do I keep my custom config, or take their update?"
92+
93+
## Summary Rules
94+
95+
1. **Don't touch `main`**. Let the sync action handle upstream data.
96+
2. **Don't commit to `local-desktop-installation-support` directly** for big work. Use feature branches.
97+
3. **Treat `local-desktop-installation-support` as your "Personal Production"**. If it's in there, it's live on your machine.

‎docs/upstream-sync.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
This guide explains how to use and configure the Upstream Sync workflow, which keeps your fork up-to-date with the upstream repository (`Dicklesworthstone/agentic_coding_flywheel_setup`).
44

55
## Overview
6+
For a high-level strategy on how to manage your fork with this workflow, please read the **[Fork Workflow Strategy](./fork-workflow-strategy.md)** guide first.
7+
68
A GitHub Action (`.github/workflows/upstream-sync.yml`) automatically syncs changes from upstream to your fork on a daily basis.
79

810
## Components
@@ -14,8 +16,8 @@ A GitHub Action (`.github/workflows/upstream-sync.yml`) automatically syncs chan
1416
1. **Daily Trigger**: Runs at 00:00 UTC.
1517
2. **Sync**: Merges `upstream/main` into a branch named `upstream-sync`.
1618
3. **Conflict Handling**:
17-
- **Clean Merge**: Creates a PR with merged changes.
18-
- **Conflict**: Commits files *with conflict markers* to the PR so you can see them in the diff.
19+
- **Clean Merge**: Automatically pushes the updates to your target branch (`local-desktop-installation-support`). No PR is created.
20+
- **Conflict**: Commits files *with conflict markers* to a new branch and creates a PR so you can resolve them.
1921
4. **AI Analysis**: If conflicts exist AND `OPENAI_API_KEY` is set in repository secrets, an AI suggestion is posted as a comment on the PR.
2022

2123
## Configuration: Setting up the API Key

0 commit comments

Comments
 (0)