|
1 | 1 | --- |
2 | 2 | name: sync-to-upstream |
3 | | -description: Use this when rebasing the fork's dev branch onto upstream/dev. Covers fetching, rebasing, conflict resolution strategy, and force-pushing. Applies to the kiennq/opencode fork tracking anomalyco/opencode. |
| 3 | +description: Use when syncing this fork's dev branch with upstream/dev, especially when rebasing, resolving conflicts, or updating the fork after rewritten history. |
4 | 4 | --- |
5 | 5 |
|
6 | | -## Use this when |
| 6 | +# Sync To Upstream |
7 | 7 |
|
8 | | -- User asks to rebase on upstream, sync with upstream, or pull upstream changes |
9 | | -- Resolving conflicts during rebase onto upstream/dev |
| 8 | +## Overview |
10 | 9 |
|
11 | | -## Prerequisites |
12 | | - |
13 | | -- Remotes: `origin` = `kiennq/opencode`, `upstream` = `anomalyco/opencode` |
14 | | -- Default branch: `dev` (not main/master) |
15 | | -- Working tree must be clean before rebasing |
16 | | - |
17 | | -## Workflow |
18 | | - |
19 | | -### 1. Fetch and assess |
20 | | - |
21 | | -```bash |
22 | | -git fetch origin --quiet && git fetch upstream --quiet |
23 | | -git log --oneline dev..upstream/dev # count new commits |
24 | | -git log --oneline --stat dev..upstream/dev -- packages/opencode/ # check for conflict-prone files |
25 | | -``` |
26 | | - |
27 | | -### 2. Ensure local dev is on top of origin/dev |
28 | | - |
29 | | -Before rebasing onto upstream, make sure local `dev` includes all commits from `origin/dev`. |
30 | | -This prevents losing any commits pushed to the fork from other machines or collaborators. |
31 | | - |
32 | | -```bash |
33 | | -# If local dev is behind origin/dev, fast-forward first |
34 | | -git merge-base --is-ancestor origin/dev dev || git rebase origin/dev |
35 | | -``` |
| 10 | +Sync upstream carefully, keep intentional fork behavior, and avoid carrying forward one-off conflict notes that no longer generalize. |
36 | 11 |
|
37 | | -If `origin/dev` has diverged (e.g. after a previous force-push from another machine), reset: |
| 12 | +## When to Use |
38 | 13 |
|
39 | | -```bash |
40 | | -git reset --hard origin/dev |
41 | | -``` |
| 14 | +- Rebasing `dev` onto `upstream/dev` |
| 15 | +- Resolving conflicts during an upstream sync |
| 16 | +- Updating `origin/dev` after a rebase |
42 | 17 |
|
43 | | -### 3. Rebase onto upstream |
44 | | - |
45 | | -```bash |
46 | | -git rebase upstream/dev |
47 | | -``` |
48 | | - |
49 | | -### 4. Resolve conflicts (if any) |
50 | | - |
51 | | -Known conflict-prone areas and resolution strategy: |
52 | | - |
53 | | -| File | Our fork changes | Resolution strategy | |
54 | | -| -------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | |
55 | | -| `src/pty/index.ts` | Buffer chunk optimization (bufferChunks/bufferSize) | **Take upstream** — their cursor-based reconnection system is more important; our chunk approach is incompatible with cursor tracking | |
56 | | -| `src/config/config.ts` | Shell metadata, attach env fields | **Merge both** — keep upstream's new fields AND our additions | |
57 | | -| `src/session/index.ts` | FileTime import, offset pagination, session list merge | **Merge both** — keep all imports from both sides | |
58 | | -| `src/cli/cmd/tui/component/dialog-model.tsx` | Lazy DialogProvider import, PROVIDER_PRIORITY, popularProvidersList memo | **Take ours** for `popularProvidersList()` since `createDialogProviderOptions` isn't imported in our lazy-import version | |
59 | | -| `src/provider/transform.ts` | Expanded Anthropic detection, whitespace trim | **Merge both** — our detection expansions layer on top of upstream | |
60 | | -| `src/tool/bash.ts` | Ring buffer (10MB cap) | **Take ours** if upstream still uses simple approach; watch for upstream ring buffer adoption | |
61 | | -| `src/question/index.ts` | Timeout + rejected event | **Take ours** if upstream removed timeouts | |
62 | | - |
63 | | -General conflict resolution rules: |
64 | | - |
65 | | -- **Imports**: Keep all imports from both sides; remove duplicates |
66 | | -- **Config schema fields**: Keep both upstream's new fields AND our additions |
67 | | -- **Core algorithms** (buffer, compaction overflow): Prefer upstream's approach if architecturally different, then layer our custom config options as early-exit checks |
68 | | -- **UI components**: Keep our lazy imports and memo patterns; use upstream's refactored component structure |
69 | | - |
70 | | -### 5. After resolving each file |
| 18 | +## Prerequisites |
71 | 19 |
|
72 | | -```bash |
73 | | -git add <resolved-files> |
74 | | -git rebase --continue |
75 | | -``` |
| 20 | +- Working tree is clean |
| 21 | +- Remotes are correct |
| 22 | +- Local `dev` includes the latest `origin/dev` commits before rebasing onto upstream |
76 | 23 |
|
77 | | -### 6. Verify and push |
| 24 | +## Workflow |
78 | 25 |
|
79 | | -```bash |
80 | | -git log --oneline -5 # verify history looks correct |
81 | | -git push origin dev --force-with-lease --no-verify # force push |
82 | | -``` |
| 26 | +1. Fetch `origin` and `upstream`. |
| 27 | +2. Make sure local `dev` is current with `origin/dev` so fork commits are not lost. |
| 28 | +3. Rebase onto `upstream/dev`. |
| 29 | +4. Resolve conflicts by taking upstream structure where it replaces old implementation details, then re-apply any intentional fork behavior that still matters. |
| 30 | +5. Verify the result and push with `--force-with-lease` if the rebase rewrote history. |
83 | 31 |
|
84 | | -If push fails with "stale info" (GitHub 500 during previous push): |
| 32 | +## Conflict Guidance |
85 | 33 |
|
86 | | -```bash |
87 | | -git fetch origin dev --quiet && git push origin dev --force-with-lease --no-verify |
88 | | -``` |
| 34 | +- Keep both sides when upstream and fork changes are independent. |
| 35 | +- Prefer upstream for broad architectural rewrites, then layer back fork-specific behavior only where it is still required. |
| 36 | +- Preserve intentional fork behavior that affects user configuration or supported workflows. |
89 | 37 |
|
90 | | -### 7. Post-rebase checks |
| 38 | +## Fork Decisions To Preserve |
91 | 39 |
|
92 | | -- New `.yml` workflow files from upstream need renaming to `.yml.disabled` (we disable upstream CI) |
93 | | -- Pre-push hook may fail on `@opencode-ai/desktop` typecheck due to missing `@tauri-apps/plugin-clipboard-manager` — use `--no-verify` to bypass |
| 40 | +- Configured `copilot-auth` plugins must remain allowed after upstream syncs. |
| 41 | +- Do not reintroduce logic that filters, skips, or blocks user-configured `copilot-auth` plugins during plugin loading. |
94 | 42 |
|
95 | | -## Our fork's additions (must preserve) |
| 43 | +## Verification |
96 | 44 |
|
97 | | -- **Persistent shell** — Windows native routing, shell metadata in bash tool output |
98 | | -- **Attach env propagation** — `x-opencode-env` header, compressed fallback env in attach/server/pty paths |
99 | | -- **Offset pagination** — `session list` API supports `before` cursor for incremental timeline loading |
100 | | -- **TUI prompt fixes** — leader-key guard on history navigation, leader-down session shortcut |
| 45 | +- Confirm there are no remaining conflict markers. |
| 46 | +- Review recent history and the final diff for accidental drops. |
| 47 | +- Run the most relevant targeted verification for any behavior touched during conflict resolution. |
101 | 48 |
|
102 | | -## Quick checklist |
| 49 | +## Quick Checklist |
103 | 50 |
|
104 | | -- [ ] Working tree clean before rebase |
105 | | -- [ ] Fetched both origin and upstream |
106 | | -- [ ] No conflict markers remain after resolution (`rg "<<<<<<|======|>>>>>>"`) |
107 | | -- [ ] Force push with `--force-with-lease --no-verify` |
108 | | -- [ ] Check for new upstream workflow files to disable |
| 51 | +- [ ] Working tree clean |
| 52 | +- [ ] Fetched `origin` and `upstream` |
| 53 | +- [ ] Local `dev` includes `origin/dev` |
| 54 | +- [ ] No conflict markers remain |
| 55 | +- [ ] Targeted verification completed |
| 56 | +- [ ] Used `--force-with-lease` only when needed |
0 commit comments