用途
这是一份 Shopify/hydrogen 仓库的分支说明，用来帮助开发者判断一项改动应属于新版 Hydrogen 还是经典 Hydrogen，避免在错误分支上开发、发布或合并。
分支布局
main 是新版 Hydrogen（截至 2026 年 10 月为 2026.10.x），与框架无关，用于所有新开发，以及原先指向 preview 的 PR。2026-04 是经典 Hydrogen（2026.4.x），仅支持 React Router 7，用于经典回溯修复和回溯发布。do-not-delete-h2-backup-use-2026-04-branch 是接管前 main 的冻结快照（经典 Hydrogen），仅作备份，不要以它为目标，也不要删除它。preview 是新版已废弃的预发布分支，不用于任何工作；它的最终树经 #4162 以重建历史（新 SHA）的方式成为 main。dist-preview 是新版的编译模板，由 main 的 Release 工作流强制推送、由 hydrogen setup 下载。dist 是经典时期的编译模板，自 2026-02 起冻结。2026-04 和备份分支受保护，禁止删除和强制推送，合并需要批准审查；各分支的 .github/workflows/release.yml 是发布范围的依据。
版本线差异
经典 Hydrogen 为 React Router 7 专门构建，最后一个大版本是 2026.4，2026.7 大版本被完全跳过。新版 2026.10.0 于 2026-10-09 首次发布，是一次重大重写，与框架无关（React Router、Next.js、Astro、Nuxt、SolidStart、SvelteKit），代码布局不同。Hydrogen 使用 CalVer YYYY.MAJOR.MINOR，MAJOR 为 Storefront API 季度发布月份（1、4、7、10）。判断改动归属：cli、create-hydrogen、hydrogen-codegen、hydrogen-react、remix-oxygen、templates/skeleton 仅存在于 2026-04；main 有 hydrogen、mini-oxygen 等。共享包如 mini-oxygen 虽在两线都存在，但只在 main 修改和发布，不得从 2026-04 合并或发版。
时间线与历史陷阱
2026-06-11 preview 从 main 分叉；2026-06-16 其历史被重写为新 SHA，此后两线无近期共同历史（merge-base 为 2022 年提交）。2026-10-09 依次：main 被复制到 2026-04 并保留备份，#4157 将发布自动化指向 2026-04；main 被 preview 内容整体覆盖（#4162）；新版从 main 发布为 2026.10.0（#4163）。接管后 Git 历史在两个方向上都会误导：6 月至 10 月的经典提交出现在 main 日志中且通过祖先检查，但内容不在 main 树中；preview 的 SHA 从不是 main 的祖先，即使改动已在。应核对文件内容而非历史，或按 PR 号搜索（git log origin/main --grep='(#4022)'）。审计分叉后经典线改动可用备份分支：git log --first-parent --oneline e73813faa..origin/do-not-delete-h2-backup-use-2026-04-branch。重定向 PR 不要整体 rebase（会重放约 2800 个旧提交），只移动 PR 自身提交；若仍指向 preview，先改为 main：git rebase --onto origin/main 011651af6。
命名与限制
公开产物（文档、变更日志、PR 描述、支持回复）中不要写“Hydrogen 3”或“Hydrogen 2”，外部称“the new version of Hydrogen”和“classic Hydrogen”（或“legacy Hydrogen”）；README 按版本表述为“Hydrogen 2026-10 or later”和“Hydrogen 2026-04 and earlier”，公开变更日志两者都不用。