From 5c1bbe5bf7b133a6e7f28d505651d7989e6d9d81 Mon Sep 17 00:00:00 2001 From: lofyer Date: Tue, 30 Jun 2026 20:56:50 +0800 Subject: [PATCH] docs(agents): document downstream fork sync workflow Describe the upstream->private mirror chain, the v-lofyer branch naming for appearance customizations, and how to run scripts/sync-github. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..83f2b8a4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,40 @@ +# Agent Instructions + +This project keeps a single source of truth for agent/contributor conventions in [`CLAUDE.md`](./CLAUDE.md). **Read [`CLAUDE.md`](./CLAUDE.md) and follow it.** + +@CLAUDE.md + +## Downstream fork workflow + +This repo is a **downstream fork** that customizes the product appearance on top of upstream `gpustack/gpustack-ui`. The mirror chain is: + +``` +upstream https://github.com/gpustack/gpustack-ui.git + | (fetch) +origin ssh://git@192.168.0.23:11022/root/gpustack-ui.git (private registry, also https://git.digiman.live) +``` + +### Goal + +Track upstream releases. When upstream changes, we pull it in, then apply our own appearance/customization changes on a dedicated branch so we keep our look-and-feel on top of the latest upstream product. + +### Branch naming + +Customization work lives on `v-lofyer` branches (e.g. `v2.2.0-lofyer`). Each time upstream ships a new version we want to follow, create a new `v-lofyer` branch from the corresponding upstream tag/branch and re-apply (or rebase) our customizations onto it. + +### Syncing from upstream + +`scripts/sync-github` mirrors upstream into the private `origin` (full mirror, force push of all branches + tags). It auto-configures the `upstream` remote on first run. + +```bash +# preview only, no push +DRY_RUN=1 ./scripts/sync-github + +# real sync (force-pushes every upstream branch + tag to origin) +./scripts/sync-github + +# also delete origin branches that no longer exist upstream (true mirror, destructive) +PRUNE_BRANCHES=1 ./scripts/sync-github +``` + +Env knobs: `UPSTREAM_URL`, `ORIGIN_REMOTE`, `UPSTREAM_REMOTE`, `PRUNE_BRANCHES`, `DRY_RUN`. After syncing, branch a fresh `v-lofyer` off the updated upstream ref and apply the appearance changes there.