Skip to content
This repository was archived by the owner on Apr 1, 2026. It is now read-only.

Commit 10eda39

Browse files
fbrbovicfbrbovic
committed
update download stats for improved tracking
1 parent ffeef63 commit 10eda39

2 files changed

Lines changed: 310 additions & 0 deletions

File tree

‎SYNC_UPSTREAM.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# Syncing SkyCode OpenCode Fork with Upstream
2+
3+
This document explains how to keep the `skycode-opencode` fork synchronized with the upstream OpenCode repository.
4+
5+
## Strategy Overview
6+
7+
**Key Principle: Keep Fork Minimal for Easy Syncing**
8+
9+
- **Plugins Location**: SkyCode plugins are **NOT** in this fork
10+
- **Plugins Location**: Plugins live in `skycode/packages/opencode-plugin/` (main repo)
11+
- **Fork Purpose**: Version control, major incompatible changes, and OpenCode customization
12+
- **Minimal Changes**: Keep fork as close to upstream as possible
13+
14+
## Why This Approach?
15+
16+
1. **Easy Upstream Syncs**: Minimal changes in fork = fewer conflicts
17+
2. **Plugin Maintenance**: Plugins evolve separately from OpenCode
18+
3. **Version Control**: Fork controls OpenCode version bundled with SkyCode
19+
4. **Clean Separation**: Core OpenCode changes vs. SkyCode extensions
20+
21+
## Quick Start
22+
23+
```bash
24+
cd skycode-opencode
25+
./sync-upstream.sh
26+
```
27+
28+
## Manual Sync Process
29+
30+
### 1. Add Upstream Remote (First Time Only)
31+
32+
```bash
33+
cd skycode-opencode
34+
git remote add upstream https://github.com/sst/opencode.git
35+
git remote -v # Verify remotes
36+
```
37+
38+
### 2. Fetch Upstream Changes
39+
40+
```bash
41+
git fetch upstream
42+
```
43+
44+
### 3. Merge Upstream into Your Branch
45+
46+
```bash
47+
# Switch to your working branch (e.g., main or dev)
48+
git checkout dev # or your branch name
49+
50+
# Merge upstream changes
51+
git merge upstream/main
52+
```
53+
54+
### 4. Resolve Conflicts (If Any)
55+
56+
If there are conflicts:
57+
```bash
58+
# Resolve conflicts in files
59+
git status # See conflicted files
60+
# Edit files to resolve conflicts
61+
62+
# After resolving:
63+
git add .
64+
git commit -m "Merge upstream: resolve conflicts"
65+
```
66+
67+
### 5. Push Changes
68+
69+
```bash
70+
git push origin dev
71+
```
72+
73+
## Automated Sync Script
74+
75+
The `sync-upstream.sh` script automates the sync process:
76+
77+
```bash
78+
cd skycode-opencode
79+
./sync-upstream.sh
80+
```
81+
82+
**What it does:**
83+
- Checks for upstream remote (adds if missing)
84+
- Fetches upstream changes
85+
- Stashes local uncommitted changes (if any)
86+
- Merges upstream/main into current branch
87+
- Restores stashed changes
88+
- Shows summary
89+
90+
## Sync Strategy
91+
92+
### Recommended Frequency
93+
- **Monthly**: Regular syncs to get upstream bug fixes and features
94+
- **As Needed**: When upstream releases important features or fixes
95+
96+
### Branch Strategy
97+
- **dev**: SkyCode's development branch (sync with upstream/main)
98+
- **main**: Stable branch (sync before releases)
99+
- **feature/***: Feature branches (sync before merging)
100+
101+
### What to Keep in Fork vs. Main Repo
102+
103+
**In Fork (skycode-opencode):**
104+
- ✅ Version pinning/compatibility changes
105+
- ✅ Major incompatible behavior changes (rare)
106+
- ✅ OpenCode core modifications needed for SkyCode
107+
- ✅ Build configuration for bundling
108+
109+
**In Main Repo (skycode):**
110+
- ✅ **All SkyCode plugins** (`packages/opencode-plugin/`)
111+
- ✅ Plugin loading/integration logic
112+
- ✅ SkyCode-specific configurations
113+
- ✅ Settings import logic
114+
115+
### Conflict Resolution
116+
117+
When conflicts occur:
118+
119+
1. **Keep Minimal Changes in Fork**:
120+
- Only essential OpenCode core changes
121+
- Version compatibility fixes
122+
- Bundling-related modifications
123+
124+
2. **Move to Main Repo When Possible**:
125+
- Plugin-related changes → Main repo
126+
- Configuration changes → Main repo
127+
- Integration logic → Main repo
128+
129+
3. **Merge Both** (when applicable):
130+
- Documentation updates
131+
- Bug fixes that don't conflict
132+
133+
## Plugin Loading Strategy
134+
135+
Since plugins are in the main repo, they're loaded via:
136+
137+
1. **Build Time**: Bundle plugin with SkyCode
138+
2. **Runtime**: OpenCode loads plugin from bundled location
139+
3. **Configuration**: Point OpenCode to SkyCode plugin location
140+
141+
**Plugin Path**: `skycode/packages/opencode-plugin/`
142+
143+
## Verifying Sync
144+
145+
```bash
146+
# Check commits ahead/behind upstream
147+
git log upstream/main..HEAD # Our commits not in upstream
148+
git log HEAD..upstream/main # Upstream commits we don't have
149+
150+
# Check diff summary
151+
git diff --stat upstream/main..HEAD
152+
153+
# Should show minimal differences (only essential changes)
154+
```
155+
156+
## Troubleshooting
157+
158+
### Upstream Remote Not Found
159+
```bash
160+
git remote add upstream https://github.com/sst/opencode.git
161+
```
162+
163+
### Merge Conflicts
164+
```bash
165+
# See conflicted files
166+
git status
167+
168+
# Use merge tool
169+
git mergetool
170+
171+
# After resolving, complete merge
172+
git add .
173+
git commit
174+
```
175+
176+
### Too Many Conflicts (Fork Drifted Too Far)
177+
178+
If fork has drifted significantly:
179+
180+
1. **Create backup branch**:
181+
```bash
182+
git branch backup-before-reset
183+
```
184+
185+
2. **Reset to upstream** (if changes are in main repo):
186+
```bash
187+
git fetch upstream
188+
git reset --hard upstream/main
189+
```
190+
191+
3. **Re-apply only essential changes**:
192+
- Re-add version pinning
193+
- Re-add bundling changes
194+
- Verify everything still works
195+
196+
### Stale Remote
197+
```bash
198+
# Update remote URL if needed
199+
git remote set-url upstream https://github.com/sst/opencode.git
200+
201+
# Verify
202+
git remote -v
203+
```
204+
205+
## Best Practices
206+
207+
1. **Sync Regularly**: Don't let fork get too far behind
208+
2. **Keep Changes Minimal**: Only essential changes in fork
209+
3. **Move to Main Repo**: When possible, keep changes in main repo
210+
4. **Test After Sync**: Run tests to ensure nothing broke
211+
5. **Document Fork Changes**: Keep track of what's different and why
212+
6. **Small Incremental Syncs**: Sync monthly rather than yearly
213+
214+
## CI/CD Integration (Future)
215+
216+
Consider adding automated sync checks:
217+
- Weekly check for upstream updates
218+
- Notification when upstream has changes
219+
- Automated test runs after sync
220+
- Automated conflict detection
221+
222+
## Related Documentation
223+
224+
- Architecture: `skycode/docs/architecture/opencode-integration-architecture.md`
225+
- Plugin Implementation: `skycode/docs/plans/opencode-bundled-implementation.md`
226+
- Plugin Code: `skycode/packages/opencode-plugin/`

‎sync-upstream.sh‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
#!/bin/bash
2+
# Sync SkyCode OpenCode Fork with Upstream
3+
# This script syncs the skycode-opencode fork with the upstream OpenCode repository
4+
5+
set -e
6+
7+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
8+
cd "$SCRIPT_DIR"
9+
10+
echo "🔄 Syncing skycode-opencode fork with upstream..."
11+
12+
# Check if upstream remote exists
13+
if ! git remote | grep -q "^upstream$"; then
14+
echo "📡 Adding upstream remote..."
15+
git remote add upstream https://github.com/opencode-ai/opencode.git || {
16+
echo "⚠️ Upstream remote might already exist with different URL"
17+
echo " Current remotes:"
18+
git remote -v
19+
read -p "Continue anyway? (y/n) " -n 1 -r
20+
echo
21+
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
22+
exit 1
23+
fi
24+
}
25+
fi
26+
27+
# Fetch upstream
28+
echo "📥 Fetching upstream changes..."
29+
git fetch upstream
30+
31+
# Get current branch
32+
CURRENT_BRANCH=$(git branch --show-current)
33+
echo "📍 Current branch: $CURRENT_BRANCH"
34+
35+
# Check if there are local uncommitted changes
36+
if ! git diff-index --quiet HEAD --; then
37+
echo "⚠️ Warning: You have uncommitted changes!"
38+
echo " Stashing changes..."
39+
git stash push -m "Auto-stash before upstream sync $(date +%Y-%m-%d)"
40+
STASHED=true
41+
else
42+
STASHED=false
43+
fi
44+
45+
# Merge upstream changes
46+
echo "🔀 Merging upstream/main into $CURRENT_BRANCH..."
47+
git merge upstream/main --no-edit || {
48+
echo "❌ Merge conflict detected!"
49+
echo " Resolve conflicts manually, then run:"
50+
echo " git add ."
51+
echo " git commit"
52+
53+
if [ "$STASHED" = true ]; then
54+
echo " Restoring stashed changes..."
55+
git stash pop
56+
fi
57+
58+
exit 1
59+
}
60+
61+
# If we stashed changes, restore them
62+
if [ "$STASHED" = true ]; then
63+
echo "♻️ Restoring stashed changes..."
64+
git stash pop || {
65+
echo "⚠️ Could not automatically restore stashed changes"
66+
echo " Run 'git stash list' to see stashed changes"
67+
}
68+
fi
69+
70+
# Show summary
71+
echo ""
72+
echo "✅ Sync complete!"
73+
echo ""
74+
echo "📊 Summary:"
75+
echo " Branch: $CURRENT_BRANCH"
76+
echo " Upstream: $(git rev-parse upstream/main --short 2>/dev/null || echo 'N/A')"
77+
echo " Local: $(git rev-parse HEAD --short)"
78+
echo ""
79+
echo "💡 Next steps:"
80+
echo " 1. Review changes: git log upstream/main..HEAD"
81+
echo " 2. Test your changes"
82+
echo " 3. Push to origin: git push"
83+
echo ""
84+

0 commit comments

Comments
 (0)