Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/closura-arc-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ jobs:
if [ -f .git/shallow ]; then unshallow=(--unshallow); fi
git fetch --no-tags --filter=blob:none "${unshallow[@]}" origin "${{ github.base_ref || github.ref_name }}:refs/remotes/origin/${{ github.base_ref || github.ref_name }}"
git fetch --no-tags --filter=blob:none https://github.com/pingdotgg/t3code.git main:refs/remotes/upstream/main
node --test scripts/fork-drift-receipt.test.mjs
node --test scripts/fork-drift-receipt.test.mjs scripts/fork-sync-plan.test.mjs
# Exit 1 means the release line is past its drift budget, which is
# reported rather than failed. Exit 2 means the receipt itself broke.
node scripts/fork-drift-receipt.mjs --base "origin/${{ github.base_ref || github.ref_name }}" || rc=$?
Expand Down
46 changes: 46 additions & 0 deletions .github/workflows/upstream-sync.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
name: Upstream fork sync

# Fetches pingdotgg/t3code main once a day. A clean merge becomes a pull
# request against release/native-0.1.10. Conflicts are filed for Platform /
# CTO. This workflow never merges that pull request and never force-pushes.
# It runs on a hosted runner because it only fetches and merges git history;
# it does not execute upstream code. The fork's ARC workflow still has to
# pass before anyone merges.
on:
schedule:
- cron: "15 8 * * *"
workflow_dispatch:

permissions:
contents: write
pull-requests: write
issues: write

concurrency:
group: t3-upstream-sync
cancel-in-progress: false

jobs:
sync:
if: ${{ github.repository == 'nullStack65/t3code' }}
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- name: Checkout the release line
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
ref: release/native-0.1.10
fetch-depth: 0
persist-credentials: true

- name: Sync upstream main
shell: bash
env:
UPSTREAM_URL: https://github.com/pingdotgg/t3code.git
BASE_BRANCH: release/native-0.1.10
GH_REPO: nullStack65/t3code
# Empty when the secret is unset. gh then uses the default token,
# which can open the pull request but cannot start its checks.
T3_FORK_SYNC_TOKEN: ${{ secrets.T3_FORK_SYNC_TOKEN }}
GH_TOKEN: ${{ secrets.T3_FORK_SYNC_TOKEN || github.token }}
run: bash scripts/upstream-sync.sh
51 changes: 35 additions & 16 deletions docs/operations/fork-sync.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,39 @@

The fleet builds and deploys from `release/native-0.1.10` on
`nullStack65/t3code`. Upstream is `pingdotgg/t3code` `main`, fetched as
`upstream/main`. This says how the two stay close. It does not perform a sync.
`upstream/main`. This says how the two stay close. The daily workflow performs
the fetch and opens the pull request. Merging that pull request is still a
separate step.

## Cadence

Once a week, Builder opens a pull request that merges `upstream/main` into a
branch cut from `release/native-0.1.10`, named `sync/upstream-<YYYY-MM-DD>`.
The pull request runs the fork's ARC CI. It merges only when that CI is green
and the one bot review round is done, like any other change.
`.github/workflows/upstream-sync.yml` runs once a day. It fetches
`upstream/main` and, when the merge into a branch cut from
`release/native-0.1.10` is clean, opens or updates
`sync/upstream-<YYYY-MM-DD>`. The pull request runs the fork's ARC CI. It
merges only when that CI is green and the one bot review round is done, like
any other change. The workflow does not merge it.

A clean update of an existing sync branch is a merge, never a force-push. If
the push is not a fast-forward, the workflow stops and says so.

The workflow opens the pull request with `T3_FORK_SYNC_TOKEN` when that
repository secret is set, so the pull request checks start. Without the
secret, the default token can open the pull request and cannot start the
other workflows. The body says that, and the pull request stays unmerged
until a `nullStack65` push starts CI.

## Conflict budget

A sync that conflicts in 25 files or fewer is resolved inside that pull
request. Fork files win where the fork deliberately diverges (the native
release line, the ARC workflow, the inbox and placement changes); upstream wins
everywhere else. A sync that conflicts in more than 25 files stops, and the
pull request says which files conflict and asks for a decision instead of
forcing the merge.
The daily job does not resolve conflicts. Any conflict updates one open issue,
titled `Upstream sync blocked`, naming Platform / CTO and listing the files.
It does not push a resolution.

A person may resolve a sync of 25 files or fewer in that pull request. Fork
files win where the fork deliberately diverges (the native release line, the
ARC workflow, the inbox and placement changes); upstream wins everywhere else.
A sync that conflicts in more than 25 files still waits for a decision. Nobody
force-pushes it.

## Drift receipt

Expand All @@ -34,11 +50,14 @@ node scripts/fork-drift-receipt.mjs --base origin/release/native-0.1.10
```

The receipt measures drift. It does not count merge conflicts, because counting
those means running the merge. The 25-file conflict budget applies when the
weekly sync pull request is opened.
those means running the merge. `scripts/upstream-sync.sh` runs that merge.
`scripts/fork-sync-plan.mjs` decides whether the result may be pushed. A
conflict, a failed merge, or a rejected push is never pushed, and the decision
sets `allowForcePush` to false.

## Who resolves

Builder owns the sync pull request and resolves conflicts inside the budget.
A sync past the budget, or one whose CI fails for a reason other than
conflicts, goes back to the delegating thread with the receipt.
The daily job files the conflict issue. Platform / CTO owns a sync past the
25-file budget. A person may resolve 25 files or fewer. A sync whose CI fails
for a reason other than conflicts goes back to the delegating thread with the
receipt.
3 changes: 3 additions & 0 deletions knip.jsonc
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,9 @@
"setup-worktree.ts",
"sign-macos.ts",
"prepare-server-compile-cache.cjs",
// The daily upstream sync runs these by path.
"fork-drift-receipt.mjs",
"fork-sync-plan.mjs",
"smoke-desktop-app.ts",
"verify-windows-desktop-artifact.ts",
],
Expand Down
128 changes: 128 additions & 0 deletions scripts/fork-sync-plan.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
#!/usr/bin/env node
// Decide what the daily upstream sync may do. It never resolves conflicts and
// never allows a force-push. The shell in scripts/upstream-sync.sh performs
// the fetch and the push this decision names.

import { readFileSync } from "node:fs";

import { CONFLICT_BUDGET } from "./fork-drift-receipt.mjs";

export { CONFLICT_BUDGET };

const OWNER = "Platform / CTO";

export function decideSync({
behind = 0,
conflictFiles = [],
pushRejected = false,
mergeFailed = false,
} = {}) {
const files = conflictFiles.filter((name) => name.length > 0);
if (pushRejected) {
return {
action: "flag-diverged",
allowForcePush: false,
owner: OWNER,
files,
};
}
if (files.length > 0 || mergeFailed) {
return {
action: "flag-conflicts",
allowForcePush: false,
owner: OWNER,
overBudget: files.length > CONFLICT_BUDGET,
files,
};
}
if (behind === 0) return { action: "up-to-date", allowForcePush: false, files: [] };
return { action: "open-pr", allowForcePush: false, files: [] };
}

export function pullRequestBody({ behind, ahead, mergeBase, ciWillStart }) {
const checks = ciWillStart
? "A repository secret opened this pull request, so the fork checks can start."
: "No T3_FORK_SYNC_TOKEN secret is set, so this pull request was opened with the default GitHub token. That token does not start other workflows. Platform / CTO: set T3_FORK_SYNC_TOKEN to a nullStack65 token, or push an empty commit as nullStack65, before treating CI as run. Do not merge while the required checks are missing.";
return [
`Upstream main is ${behind} commits ahead of release/native-0.1.10. The fork has ${ahead} commits that are not upstream. Merge base \`${mergeBase}\`.`,
"",
"This merges upstream/main into a branch cut from the release line. The workflow does not merge the pull request.",
"",
checks,
"",
"Model: github-actions",
"Task: sync",
"",
"Deploy: fleet",
"",
].join("\n");
}

export function issueBody({ decision, behind, ahead, mergeBase, date }) {
const files = decision.files ?? [];
const budget =
decision.overBudget === true
? `Conflicts in ${files.length} files, past the ${CONFLICT_BUDGET}-file budget. This needs a decision before anyone resolves it.`
: `Conflicts in ${files.length} file${files.length === 1 ? "" : "s"}. The daily sync does not resolve conflicts.`;
const diverged =
decision.action === "flag-diverged"
? "The sync branch already differs, so updating it would take a force-push. The push was not retried."
: budget;
return [
`Platform / CTO: the upstream sync for ${date} stopped.`,
"",
diverged,
`The release line is ${behind} commits behind upstream and ${ahead} commits ahead. Merge base \`${mergeBase}\`.`,
"Do not force-push. Do not bypass CI.",
"",
"Files:",
...(files.length > 0
? files.map((name) => `- ${name}`)
: ["- (push rejected before a file list was available)"]),
"",
].join("\n");
}

function argument(args, name) {
const index = args.indexOf(name);
return index === -1 ? undefined : args[index + 1];
}

function main() {
const args = process.argv.slice(2);
const conflictsPath = argument(args, "--conflicts-file");
const conflictFiles =
conflictsPath === undefined
? []
: readFileSync(conflictsPath, "utf8")
.split("\n")
.map((line) => line.trim())
.filter((line) => line.length > 0);
const behind = Number(argument(args, "--behind") ?? "0");
const ahead = Number(argument(args, "--ahead") ?? "0");
const mergeBase = argument(args, "--merge-base") ?? "";
const date = argument(args, "--date") ?? "";
const ciWillStart = args.includes("--ci-will-start");
const decision = decideSync({
behind,
conflictFiles,
pushRejected: args.includes("--push-rejected"),
mergeFailed: args.includes("--merge-failed"),
});
const body =
decision.action === "open-pr"
? { pullRequest: pullRequestBody({ behind, ahead, mergeBase, ciWillStart }) }
: decision.action === "up-to-date"
? {}
: { issue: issueBody({ decision, behind, ahead, mergeBase, date }) };
process.stdout.write(`${JSON.stringify({ ...decision, ...body })}\n`);
}

if (import.meta.url === `file://${process.argv[1]}`) {
try {
main();
} catch (error) {
process.stderr.write(`fork-sync-plan: ${error.message}\n`);
process.exit(2);
}
}
Loading
Loading