Repository navigation
docs(agents): add an upstream-sync skill #32
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. Weβll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,120 @@ | ||
| --- | ||
| name: upstream-sync | ||
| description: Bring upstream pingdotgg/t3code into this fork's dev_vm in three gated stages, a scout report, the merge, then a Forgejo release. Use when asked to sync, merge, or pull upstream changes. | ||
| --- | ||
|
|
||
| # Sync upstream into dev_vm | ||
|
|
||
| Three stages. The scout ends at a report and an **approval gate**: the merge and | ||
| release start only after Andrei approves that report. Each stage's criterion | ||
| says when it is done. | ||
|
|
||
| The scratch worktree lives outside the repository (`/tmp/t3-merge-scout`), so | ||
| the main checkout stays clean on `dev_vm` until the merge is approved. Every | ||
| command names `dev_vm` rather than `HEAD`, since the skill may run from another | ||
| branch. Shell variables do not survive the approval gate, so recompute `MB` | ||
| when a later stage needs it. | ||
|
|
||
| ## 1. Scout | ||
|
|
||
| ```bash | ||
| git fetch upstream && git fetch origin # local dev_vm must equal origin/dev_vm | ||
| MB=$(git merge-base dev_vm upstream/main) | ||
| git worktree add --detach /tmp/t3-merge-scout dev_vm | ||
| cd /tmp/t3-merge-scout && git merge --no-ff --no-commit upstream/main | ||
| ``` | ||
|
|
||
| Gather, in the scratch worktree: | ||
|
|
||
| - **What's new**: `git log --no-merges $MB..upstream/main`, with commit types | ||
| counted and every `feat`/`perf` read. Highlight changes that touch fork | ||
| features, migrations, updating, or the mobile native build. | ||
| - **Conflicts**: resolve each one in the scratch tree, keeping the fork's intent | ||
| on upstream's new structure. Use `resolving-merge-conflicts` for anything | ||
| non-trivial. | ||
| - **Overlap**: files changed on both sides, | ||
| `comm -12 <(git diff --name-only $MB dev_vm | sort) <(git diff --name-only $MB upstream/main | sort)`. | ||
| A clean textual merge can still break a fork feature, so read the upstream | ||
| commits behind each overlapping file. | ||
| - **Redundant fork patches**: for each fork feature or fix | ||
| (`git log --no-merges upstream/main..dev_vm`), check whether upstream now does | ||
| the same thing. If it does, propose dropping the fork's version. | ||
| - **Migration ledger**: list upstream's new migrations, and read the live ledger | ||
| read-only: | ||
| `sqlite3 "file:$HOME/.local/share/t3code/userdata/statev2.sqlite?mode=ro" "select * from effect_sql_migrations order by migration_id"`. | ||
| Every recorded id must carry upstream's name. The fork never adds rows to this | ||
| ledger; fork schema goes in its own table. | ||
| - **Build health**: install dependencies, then typecheck each package that | ||
| holds a file from `git diff --name-only $MB dev_vm`. Upstream CI covers the | ||
| rest. Then run these tests (see Gotchas): the fork's | ||
| (`git diff --name-only $MB dev_vm -- '*.test.ts' '*.test.tsx'`), the tests for | ||
| overlapping files, and every test upstream added or changed in a directory | ||
| that holds a fork-changed file. New upstream tests there can assert behavior | ||
| the fork deliberately changed. | ||
|
|
||
| Done when the report covers: what's new, every conflict and its resolution, each | ||
| adaptation that the typecheck or tests forced, redundant fork patches, semantic | ||
| gaps found in the overlap (each with a recommendation: fix now or follow up), | ||
| the migration ledger, and typecheck and test results. Present the report, then | ||
| stop and wait for approval. | ||
|
|
||
| ## 2. Merge | ||
|
|
||
| 1. Fetch again. If `upstream/main` moved, copy the resolved files out, stage | ||
| everything, `git merge --abort`, and merge the new tip. Restore a saved | ||
| resolution only for a file that | ||
| `git diff --name-only <old tip> upstream/main` does not list. Resolve the | ||
| listed files again, since a copy would discard upstream's newer content. | ||
| Then rerun typecheck and tests. | ||
| 2. Commit in the scratch worktree as | ||
| `merge(upstream): integrate <Month D> updates with fork compatibility`. The | ||
| body names each adaptation and why, with no list of upstream features. | ||
| 3. The pre-commit hook formats staged files, so check that the result still | ||
| differs from upstream only in fork files. This must print nothing: | ||
| `comm -23 <(git diff --name-only upstream/main HEAD | sort) <(git diff --name-only $(git merge-base dev_vm upstream/main) dev_vm | sort)` | ||
| (run before the fast-forward, while `dev_vm` is still the pre-merge tip). | ||
| 4. In the main checkout, `git merge --ff-only <merge commit>`, then | ||
| `git push origin dev_vm`. | ||
|
|
||
| Done when `dev_vm` on origin is the verified merge commit. | ||
|
|
||
| ## 3. Release | ||
|
|
||
| Follow [Forgejo package operations](../../../docs/operations/forgejo-packages.md), | ||
| but run its stages one at a time instead of `npm run release:forgejo`, which | ||
| starts Android straight after the WSL desktop build: | ||
|
|
||
| 1. `node scripts/t3code-forgejo.mjs publish --output /tmp/t3-release-artifact`. | ||
| Read the version and commit from its `build.json`. | ||
|
Comment on lines
+87
to
+88
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
After one successful release, Useful? React with πΒ / π. |
||
| 2. `scripts/t3code-desktop-release --version V --ref C`. | ||
| 3. Before Android, confirm WSL is idle and the Windows host has room for this | ||
| VM to grow to about 18 GB. A starved Android build freezes the VM. WSL's own | ||
| `uptime` and `free` should show it idle, and the host's free memory should | ||
| cover the VM's growth (18 GB minus `free -g` total here): | ||
| `ssh wsl_worker '/mnt/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe -NoProfile -Command "(Get-CimInstance Win32_OperatingSystem).FreePhysicalMemory/1MB"'`. | ||
| Then run `scripts/t3code-android-release --version V --ref C`, and keep an | ||
| eye on swap here while it builds. | ||
| 4. Download the published server package | ||
| (`node scripts/t3code-forgejo.mjs download --version V --output DIR`) and | ||
| compare its hash with the built artifact. | ||
|
|
||
| Done when the report gives the version, the commit, the hash match, and each | ||
| client build's outcome. A failed client build is retried on its own, never by | ||
| releasing again. Releasing does not install anything or restart a service. | ||
|
|
||
| Finish with `git worktree remove --force /tmp/t3-merge-scout`. | ||
|
|
||
| ## Gotchas | ||
|
|
||
| - `scripts/setup-worktree.ts` needs `T3CODE_PROJECT_ROOT`, and Volta cannot | ||
| find `vp` in a worktree that has no `node_modules` yet. Install with the main | ||
| checkout's binary: | ||
| `/home/menshikov/projects/t3code/node_modules/.bin/vp i -- --yes`. | ||
| - Typecheck a package with `/tmp/t3-merge-scout/node_modules/.bin/tsc-rs --noEmit` | ||
| run from its directory. It prints hundreds of Effect suggestions; only lines | ||
| matching `: error TS` count. | ||
|
Comment on lines
+113
to
+115
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
When a fork-changed package does not use the standard TypeScript check, this command runs the wrong validator. For example, AGENTS.md reference: AGENTS.md:L98-L101 Useful? React with πΒ / π. |
||
| - Run tests from the scratch root with `./node_modules/.bin/vp test run <files>`. | ||
| - `git merge --abort` refuses while edits are unstaged. Stage them first. | ||
| - New upstream tests can assert upstream behavior that the fork deliberately | ||
| changed (security headers, version comparison). Update the test to the fork's | ||
| behavior, and name it in the merge commit body. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fresh evidence after the earlier merge-stage fix is that the scout bullets still consume
$MBafter the setup command has returned. When these steps run in separate terminal calls,$MBis empty, so this first diff compares the in-progress merge worktree againstdev_vminstead of enumerating fork changes since the merge base; fork-only packages and tests can consequently be omitted from validation. Recompute the merge base inline or persist it across calls.AGENTS.md reference: AGENTS.md:L98-L101
Useful? React with πΒ / π.