workflow-ship-change

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Workflow: ship a change

工作流：交付更改

A change is done only when all of these are true, and the report shows each one:

Screenshots of the real rendered game: the start state, the key moment and the result. They're shown inline in the report.
Its own changelog version, with its pictures on the in-game changelog page.
Verified:
- your own tests;
- the tests of commits you merged in;
- the asset checks;
- the full suite, run on the pushed commit.
Committed: one cohesive commit, with only your own files staged.
Pushed to
```
main
```
as a fast-forward, and confirmed on GitHub.
Live: the build of that exact
```
main
```
is published, and confirmed working on the real domain.
Measured: the sizes of the commit, the push, any upload and the publish, all measured, never estimated.

Pushing and publishing are standing authorizations for the project's own repository and live site. So don't ask before them, except where a guardrail below says stop. Read the project's

AGENTS.md

before starting, and this skill's

references/<project>.md

if there is one. Project rules change often, and wherever they differ from this skill, they win.

一项更改只有满足以下所有条件才算完成，并且报告中必须展示每一项：

真实渲染游戏的截图：开始状态、关键时刻和结果。截图需在报告中内联展示。
独立的 changelog 版本，并将对应图片添加到游戏内 changelog 页面。
已验证：
- 你自己的测试；
- 你合并进来的 commits 所涉及的测试；
- 资源检查；
- 在已推送的 commit 上运行的完整测试套件。
已 commit：一个内聚的 commit，并且只暂存你自己的文件。
已 push：以 fast-forward 方式推送到
```
main
```
，并在 GitHub 上确认。
已上线：发布与该
```
main
```
完全一致的构建版本，并在真实域名上确认其正常工作。
已实测：commit、push、任何上传及发布的大小均须实测，不得估算。

对项目自有仓库和线上站点的 push 与 publish 属于长期授权。因此，无需事先询问，但下文护栏明确要求停止的情况除外。开始前阅读项目的

AGENTS.md

；如果存在，还要阅读此 skill 的

references/<project>.md

。项目规则经常变化；凡与本 skill 冲突之处，均以项目规则为准。

Guardrails: stop and ask the user

护栏：停止并询问用户

Any upload over 50 MB. That covers a git push, a Netlify deploy, a media release, and files sent to any outside service.
- Measure first (
```
upload-size.sh
```
  , or the pack size
```
push-main.sh
```
  prints), and state the size when asking.
- Count the whole operation, and never split it to get under.
- A full Supabase media release (about 861 MiB) always needs asking.
A force-push, rewriting remote history, changing repository visibility, or pushing to another repository.
A new site or project, or changing a site's access, domain or DNS, unless the task is exactly that and the user asked for it.
When the permission check blocks a deploy, rollback or upload: stop. Don't retry it another way or through another thread. Tell the user the exact click path or command.
Live broken after your publish: say so first in your report, with the measured evidence and the rollback click path. Don't bury it.

任何超过 50 MB 的上传。 这涵盖 git push、Netlify deploy、media release，以及发送给任何外部服务的文件。
- 先进行测量（使用
```
upload-size.sh
```
  ，或查看
```
push-main.sh
```
  打印的 pack size），询问时说明大小。
- 按整个操作计算，绝不能通过拆分操作来规避限制。
- 完整的 Supabase media release（约 861 MiB）始终需要询问。
force-push、重写远程历史、更改仓库可见性，或推送到另一个仓库。
创建新站点或新项目，或更改站点的访问权限、域名或 DNS，除非当前任务正是这些工作且用户已明确要求。
当权限检查阻止 deploy、rollback 或 upload 时：立即停止。不要改用其他方式或在其他会话中重试。向用户提供准确的点击路径或命令。
发布后线上出现故障：在报告开头第一时间说明，并附上实测证据和 rollback 点击路径。不要淡化此问题。

Guardrails: never

护栏：绝不做

Never publish anything but the clean, pushed
```
origin/main
```
. No unmerged branch, no uncommitted file.
Never deploy large media to Netlify as a fallback; media lives in Supabase Storage.
Never publish to a host the project has retired, even if old scripts still point at it.
Never run the broad image optimizer (
```
pnpm images:optimize
```
, or
```
optimize-images.py --apply
```
). It rewrites other sessions' pending images. Use
```
runtime-assets.py --only '<your glob>'
```
, then
```
--verify
```
.
Never stage credentials,
```
.env*
```
,
```
node_modules
```
, caches or build output, and never use
```
git add -A
```
in a shared checkout.
Never call a local commit pushed, or a deploy live, until you've confirmed it on the remote or the domain.
Never kill a process you didn't start. Check its working folder first:
```
lsof -a -p <pid> -d cwd
```
.

绝不使用除干净且已 push 的
```
origin/main
```
之外的任何内容进行发布。不得使用未合并的 branch，也不得包含未 commit 的文件。
绝不能将大型 media 部署到 Netlify 作为备用方案；media 应存放在 Supabase Storage 中。
绝不能发布到项目已停用的 host，即使旧脚本仍指向该 host。
绝不能运行范围广泛的图片优化器（
```
pnpm images:optimize
```
或
```
optimize-images.py --apply
```
）。它会重写其他会话的待处理图片。应使用
```
runtime-assets.py --only '<your glob>'
```
，然后执行
```
--verify
```
。
绝不暂存凭据、
```
.env*
```
、
```
node_modules
```
、缓存或 build output；在共享 checkout 中也绝不能使用
```
git add -A
```
。
在确认 remote 或域名上的状态之前，绝不能将本地 commit 称为已 push，也不能将 deploy 称为已上线。
绝不能终止并非由你启动的进程。请先检查其工作目录：
```
lsof -a -p <pid> -d cwd
```
。

Steps

步骤

0. Before you start

0. 开始之前

Run
```
git fetch
```
, then
```
git log origin/main --oneline -30
```
, and search for your area. Look in the sibling worktrees (
```
git -C <wt> diff --stat
```
) for someone already making the same edit.
Work in your own worktree on a branch off
```
origin/main
```
. Other sessions edit the shared checkout live.

运行
```
git fetch
```
，然后运行
```
git log origin/main --oneline -30
```
，并搜索你负责的区域。查看同级 worktree（
```
git -C <wt> diff --stat
```
），确认是否有人正在做相同修改。
在自己的 worktree 中工作，并使用从
```
origin/main
```
创建的 branch。其他会话会直接在共享 checkout 中编辑。

1. Screenshots

1. 截图

Capture the real game at 1600×900 using the project's review fixtures (
```
?review=<name>
```
). Take the start, the key moment and the result.
If the project names a capture tool, use it. Otherwise capture headlessly over CDP (see the
```
workflow-progress-screenshots
```
skill), and say which you used.
Look at every picture before using it. Stray toasts, stale numbers, or the wrong scene mean recapture.
Label them honestly: headless browser captures, and a phone-sized viewport is not a device test.
Keep capture scripts in the worktree's gitignored
```
qa/captures/
```
; the session scratchpad is wiped on restart.

使用项目的 review fixtures（
```
?review=<name>
```
），以 1600×900 捕获真实游戏。分别截取开始状态、关键时刻和结果。
如果项目指定了 capture tool，就使用它。否则通过 CDP 以 headless 方式截取（参见
```
workflow-progress-screenshots
```
skill），并说明使用了哪一种。
使用前逐张查看图片。杂散 toast、过期的数字或错误的场景都意味着需要重新截取。
如实标注：headless 浏览器截图；手机尺寸的 viewport 不能算作设备测试。
将 capture scripts 保留在 worktree 中被 gitignore 的
```
qa/captures/
```
目录；session scratchpad 会在重启后被清空。

2. Changelog version

2. Changelog 版本

Follow the project's changelog rules exactly: format, versioning, and how pictures are added.
Write for players: what they can see or do now, with no file names or hashes.
Changes to tests, tooling, docs or rules get no version.
If another session took your version number, renumber yours on merge, and keep their entries.

严格遵循项目的 changelog 规则，包括格式、版本号规则以及添加图片的方式。
面向玩家来写：说明他们现在能看到或能做什么，不要出现文件名或 hash。
对测试、工具、文档或规则的更改不创建版本。
如果另一个 session 已占用你的版本号，合并时重新编号，并保留他们的条目。

3. Verify

3. 验证

Run the suites your change touches as you go.
After merging
```
main
```
, also run every test file the incoming commits touched:
```
git diff --name-only <old-base> <new-base> -- tests
```
.
Run the image verify if images shipped.
The full suite takes 10–40 minutes on a busy machine. Run it with
```
run_in_background
```
and read the log. Re-run a timeout-looking failure on its own before calling it real.
Report honestly which runs were full and which were targeted, with pass and fail counts.

在开发过程中运行此次更改涉及到的测试套件。
合并
```
main
```
后，还要运行传入 commits 触及的每个测试文件：
```
git diff --name-only <old-base> <new-base> -- tests
```
。
如果发布了图片，运行图片验证。
繁忙机器上运行完整测试套件需要 10–40 分钟。使用
```
run_in_background
```
并读取日志。将看起来像超时的失败单独重跑后，才能将其判定为真实失败。
如实报告哪些运行是完整测试、哪些是定向测试，并提供通过和失败数量。

4. Commit

```
git diff --cached
```
must be empty before you start.
Stage explicit paths only.
Run
```
commit-size.sh
```
on the staged changes; its numbers go in the report.
One commit per cohesive change. While still iterating, amend a single work-in-progress commit instead of piling up small ones.
Write the message in the repo's style, ending with the attribution line the system gives you.

开始前，
```
git diff --cached
```
必须为空。
只显式暂存指定路径。
对已暂存的更改运行
```
commit-size.sh
```
；其数据需写入报告。
每项内聚的更改对应一个 commit。在仍处于迭代阶段时，应 amend 同一个进行中的 commit，而不是累积多个小 commit。
commit message 应采用仓库的既有风格，并以系统提供的 attribution 行结尾。

5. Merge and push

5. 合并与推送

```
git fetch
```
, then
```
git rebase origin/main
```
(or merge, on a shared branch).
Resolve conflicts keeping everyone's work. For generated JSON (image audit, manifests), take upstream's file, re-add your own records, and recompute totals with the project's tool.
```
node --check
```
every
```
src
```
and
```
tests
```
file. Then run your tests plus the incoming commits' tests.
```
push-main.sh
```
:
- it refuses anything that isn't a fast-forward;
- it measures the pack and stops over 50 MB;
- it pushes with
```
--progress
```
  and prints git's "Writing objects" line (the bytes sent);
- it confirms
```
origin/main
```
  equals HEAD.
If
```
main
```
moved, go back to step 1.
Run the full suite on the pushed commit, and fix forward if it breaks.

运行
```
git fetch
```
，然后运行
```
git rebase origin/main
```
；如果位于共享 branch 上，则执行 merge。
解决冲突时保留所有人的工作。对于生成的 JSON（图片审计、manifests），采用上游版本的文件，重新加入自己的记录，并使用项目工具重新计算汇总数据。
对每个
```
src
```
和
```
tests
```
文件执行
```
node --check
```
。然后运行自己的测试以及传入 commits 的测试。
```
push-main.sh
```
：
- 它会拒绝任何非 fast-forward 的推送；
- 它会测量 pack 大小，并在超过 50 MB 时停止；
- 它使用
```
--progress
```
  推送，并打印 git 的 "Writing objects" 行（已发送的字节数）；
- 它会确认
```
origin/main
```
  与 HEAD 相同。
如果
```
main
```
发生变化，请返回步骤 1。
在已推送的 commit 上运行完整测试套件；如果测试失败，进行向前修复。

6. Publish live

6. 发布上线

Build in a checkout whose HEAD is exactly
```
origin/main
```
and whose tracked files are clean.
If the build changes a tracked file, commit and push that file first, then build again.
Measure what will be uploaded (
```
upload-size.sh dist
```
, plus any media release). Over 50 MB, stop and ask.
Deploy to a draft or preview URL first. Run
```
verify-live.sh <draft-url>
```
: the page, its scripts and art, and the gate route. Promote to production only when it passes. This step exists because a production deploy once went out without its edge function: the site served its page but 404'd every image, and nobody could play.
After promoting, run
```
verify-live.sh
```
on the real domain. Record the deploy ID, the publication time, the live game version, and the bytes sent.
If another session published after you, that's fine as long as it also published
```
main
```
.

在一个 HEAD 恰好为
```
origin/main
```
且 tracked files 干净的 checkout 中执行构建。
如果构建改动了某个 tracked file，先 commit 并 push 该文件，然后重新构建。
测量将要上传的内容（
```
upload-size.sh dist
```
，以及任何 media release）。如果超过 50 MB，停止并询问用户。
先部署到 draft 或 preview URL。 运行
```
verify-live.sh <draft-url>
```
：检查页面、脚本和美术资源，以及 gate route。只有通过验证后，才能提升到 production。此步骤之所以存在，是因为有一次 production deploy 在缺少 edge function 的情况下上线：站点页面可以打开，但所有图片都返回 404，导致玩家无法游玩。
提升到 production 后，在真实域名上运行
```
verify-live.sh
```
。记录 deploy ID、发布时间、live game version 和已发送的字节数。
如果你之后又有其他 session 执行了发布，只要它发布的也是
```
main
```
，就没有问题。

Report

报告

Short, in this order:

The commit hash, pushed and confirmed. Commit size: files, total size, largest files. Push size: the bytes sent.
Live: URL, deploy ID, time, live version, and the
```
verify-live.sh
```
result. Upload size: bytes sent, built-site size, and any media release. If you didn't publish, say why (for example "held: needs a media release over 50 MB; asking").
What changed, for a player, plus the changelog version and title.
Tests: which runs were full and which targeted, with pass and fail counts.
Screenshots with captions, labelled as headless captures.
Anything deferred or departed from, and why.

报告应简短，并按以下顺序排列：

commit hash、已 push 并确认。Commit size：文件数、总大小和最大的文件。Push size：已发送的字节数。
Live：URL、deploy ID、时间、live version 和
```
verify-live.sh
```
结果。Upload size：已发送的字节数、构建产物大小，以及任何 media release。如果未发布，说明原因（例如“暂缓：需要发布超过 50 MB 的 media release；正在询问”）。
面向玩家说明变更内容，以及 changelog version 和 title。
测试：说明哪些是完整运行、哪些是定向运行，并提供通过和失败数量。
截图及说明文字，并标注为 headless 截图。
任何延期事项或偏离本工作流之处，以及原因。