MacWave 3.0

Release Note 更新日志

本次为不兼容更新：包与版本数据从「代码仓库的分支」迁出到独立仓库，依赖数据目录由 surfboard/ 改名为 deps/；并且 3.0 不能通过 wave selfupdate 升级，必须用 install.sh 重新安装。

本次是不兼容更新

3.0 之前，包元数据与版本数据都放在代码仓库 MacWaveOrg/MacWave 的分支里（infosource / configdata），依赖数据则放在该分支的 surfboard/ 目录下。

3.0 起：

• 数据迁到各自的独立仓库，路径与引用全部改变；
• 依赖数据的目录名 surfboard/ → deps/；
• 官网站点从代码仓库的 gh-pages 分支迁到独立仓库。

旧版本（≤ 2.6.1）读的仍是旧地址。 旧分支目前还在，但已冻结、不再更新——老版本继续能用，只是拿不到 3.0 之后的内容。要拿到 3.0，请按下文用 install.sh 重装。

不能通过 selfupdate 升级到 3.0

3.0 的 selfupdate.sh 增加了跨大版本守卫：当目标版本与当前已装版本的大版本号不同时，直接拒绝并提示改用 install.sh。

当前版本	目标	行为
2.x（任意）	3.0	拒绝，提示改用 install.sh ⛔
3.0	3.0	已是最新，短路退出
3.0	3.x	正常自更新 ✅

这是一条通用规则，不是 3.0 专属：每个大版本的第一个版本、以及任何跨大版本升级，都不能走 selfupdate（这类升级通常同时改动仓库与目录结构）。守卫写在 selfupdate.sh 里、随目标分支下发，因此以后每个大版本都自动生效，无需逐版写死在数据里。

仓库 / 分支迁移前后地址

内容	迁移前	迁移后
代码仓库	MacWaveOrg/MacWave	不变（仍是 MacWaveOrg/MacWave；main 与 3.0 同步）
包元数据（描述 / 下载地址 / 校验值）	MacWave 仓库的 infosource 分支 raw.githubusercontent.com/MacWaveOrg/MacWave/infosource/pkg/…	MacWaveOrg/infosource 仓库的 main 分支 raw.githubusercontent.com/MacWaveOrg/infosource/main/pkg/…
依赖数据	同一分支的 surfboard/ 目录 …/MacWaveOrg/MacWave/infosource/surfboard/depsinfo_{arch}/…	新仓库、目录改名 deps/ …/MacWaveOrg/infosource/main/deps/depsinfo_{arch}/…
包列表 API	api.github.com/repos/MacWaveOrg/MacWave/contents/pkg/pkginfo_{arch}?ref=infosource	api.github.com/repos/MacWaveOrg/infosource/contents/pkg/pkginfo_{arch}?ref=main
版本 / 迁移数据	MacWave 仓库的 configdata 分支 raw.githubusercontent.com/MacWaveOrg/MacWave/configdata/…	MacWaveOrg/configdata 仓库的 main 分支 raw.githubusercontent.com/MacWaveOrg/configdata/main/…
官网站点	MacWave 仓库的 gh-pages 分支	MacWaveOrg/Pages 仓库的 main 分支（自定义域仍是 macwave.org）
测试包（格式测试用）	MacWaveOrg/MacWavePkgTest	MacWaveOrg/pkgtest（旧名 301 重定向）
迁移前的历史归档	—	新增 MacWaveOrg/legacy-MacWave：迁移前的完整镜像，已归档只读，保留全部提交历史

为什么要发一版

这次迁移改动的是数据来源，而不是功能，但必须发一版才能把「怎么升级」送达用户：

因为 3.0 无法用 wave selfupdate 到达（见上），release 说明本身就是升级通知——存量用户需要知道要改用 install.sh 重装，而不是等一个永远不会到来的自更新。

升级方式

重新安装（推荐）：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/MacWaveOrg/MacWave/HEAD/lib/install.sh)"

安装脚本现在从 configdata 读取版本号与代码来源分支（不再写死在脚本里），因此它会自动安装 configdata 当前公布的版本（本次为 3.0）。

其他改动

• lib/install.sh：MACWAVE_VERSION 与代码来源分支改为从 configdata 的 versiondata/latest_version 读取（version / branch 一起读，保证「下载的代码」与「写进 VERSION.json 的版本号」对应同一版本）
• lib/selfupdate.sh：新增跨大版本守卫（见上）
• 新增工作流 Sync main with the release branch：main 与「发布分支」自动互相检测并快进同步；发布分支由 configdata 的 branch 字段决定，分叉时直接报错交人工处理，历史分支（2.3 / 2.4 / 2.5）不会被触碰
• configdata：versiondata/latest_version 更新为 3.0（构建号 281D2012，branch: "3.0"），并新增 updatedata/3.0 迁移副本（沿用自 2.5 起的惯例）
• 官网与 README 显示的版本号同步为 3.0
• 站点迁移后 macwave.org 一度返回 404（新仓库尚未构建），已通过触发构建修复

验证方式

• 回归套件：隔离沙箱 64 条断言全部通过（64 PASS / 0 FAIL / 0 SKIP），其中包含「VERSION.json 版本与 configdata 一致」的断言
• 跨大版本守卫实测：在一次性沙箱 HOME 里以已装 2.6.1、目标 3.0 运行 → 被拒绝（退出码 1），VERSION.json 未改动、未写入任何文件；同大版本（3.0 → 3.1）不被误拦
• 站点实测：https://macwave.org/ 返回 200，页面显示 Latest Version : 3.0
• 双向同步实测：只推 main → 3.0 自动快进；只推 3.0 → main 自动快进；分叉场景报错且两边均不动（本地模拟验证）

---

Release Notes

This is a breaking update: package and version data moved out of the code repository's branches into dedicated repositories, the dependency data folder was renamed surfboard/ → deps/, and 3.0 cannot be reached with wave selfupdate — it must be installed with install.sh.

This is a breaking update

Before 3.0, the package metadata and the version data both lived in branches of the code
repository MacWaveOrg/MacWave (infosource / configdata), with the dependency data
under a surfboard/ directory on that branch.

As of 3.0:

• the data moved into dedicated repositories, changing every path and reference;
• the dependency data folder was renamed surfboard/ → deps/;
• the website moved from the code repository's gh-pages branch into its own repository.

Older versions (<= 2.6.1) still read the old addresses. Those branches are still
present but frozen — old installs keep working, they simply stop receiving anything
published after 3.0. To get 3.0, reinstall with install.sh as described below.

You cannot update to 3.0 with selfupdate

selfupdate.sh now carries a cross-major guard: when the target version's major
number differs from the installed one, it refuses outright and points at install.sh.

Installed	Target	Behaviour
2.x (any)	3.0	refused, points at install.sh ⛔
3.0	3.0	already up to date, exits early
3.0	3.x	self-update runs ✅

This is a general rule, not a 3.0 special case: the first release of every major
version — and any cross-major upgrade — cannot go through selfupdate (such upgrades
usually change both repositories and directory layout). The guard lives in
selfupdate.sh and is delivered by the target branch, so every future major gets it
automatically instead of it being hardcoded per release.

Repository / branch addresses before and after

What	Before	After
Code repository	MacWaveOrg/MacWave	unchanged (still MacWaveOrg/MacWave; main and 3.0 kept in sync)
Package metadata (description / download url / checksum)	infosource branch of MacWave raw.githubusercontent.com/MacWaveOrg/MacWave/infosource/pkg/…	main branch of MacWaveOrg/infosource raw.githubusercontent.com/MacWaveOrg/infosource/main/pkg/…
Dependency data	surfboard/ on that same branch …/MacWaveOrg/MacWave/infosource/surfboard/depsinfo_{arch}/…	new repository, folder renamed deps/ …/MacWaveOrg/infosource/main/deps/depsinfo_{arch}/…
Package listing API	api.github.com/repos/MacWaveOrg/MacWave/contents/pkg/pkginfo_{arch}?ref=infosource	api.github.com/repos/MacWaveOrg/infosource/contents/pkg/pkginfo_{arch}?ref=main
Version / migration data	configdata branch of MacWave raw.githubusercontent.com/MacWaveOrg/MacWave/configdata/…	main branch of MacWaveOrg/configdata raw.githubusercontent.com/MacWaveOrg/configdata/main/…
Website	gh-pages branch of MacWave	main branch of MacWaveOrg/Pages (custom domain is still macwave.org)
Test packages (format tests)	MacWaveOrg/MacWavePkgTest	MacWaveOrg/pkgtest (old name 301-redirects)
Pre-migration archive	—	new MacWaveOrg/legacy-MacWave: a full mirror of the repository as it was, archived read-only, all commit history kept

Why cut a release at all

This migration changed where the data comes from, not what it does, yet a release is
the only way to deliver the "how to upgrade" message:

because 3.0 cannot be reached with wave selfupdate (see above), these release notes
are themselves the upgrade notice — existing users need to know they must reinstall
with install.sh rather than wait for a self-update that will never arrive.

How to upgrade

Reinstall (recommended):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/MacWaveOrg/MacWave/HEAD/lib/install.sh)"

The installer now reads the version and the code source branch from configdata
instead of hardcoding them, so it installs whatever version configdata currently
publishes (3.0 as of this release).

Other changes

• lib/install.sh: MACWAVE_VERSION and the code source branch are now read from
  configdata's versiondata/latest_version (version / branch are read together so
  the code downloaded and the version recorded in VERSION.json always match)
• lib/selfupdate.sh: the cross-major guard described above
• new workflow Sync main with the release branch: main and the release branch
  detect each other and fast-forward automatically; the release branch comes from
  configdata's branch field, divergence fails the run for a human, and historical
  branches (2.3 / 2.4 / 2.5) are never touched
• configdata: versiondata/latest_version bumped to 3.0 (build 281D2012,
  branch: "3.0") plus a copy of the 2.5 config migration at updatedata/3.0, following
  the convention kept since 2.5
• the version shown on the site and in the READMEs is now 3.0
• after the site move, macwave.org briefly returned 404 (the new repository had never
  been built); fixed by triggering a build

How it was verified

• Regression suite: all 64 assertions pass in an isolated sandbox
  (64 PASS / 0 FAIL / 0 SKIP), including the check that VERSION.json matches
  configdata
• Cross-major guard, exercised for real: in a throwaway sandbox HOME, installed
  2.6.1 upgrading to 3.0 is refused (exit code 1) with VERSION.json untouched
  and no file written; a same-major upgrade (3.0 → 3.1) is not blocked
• Site: https://macwave.org/ returns 200 and shows Latest Version : 3.0
• Two-way sync: pushing only main fast-forwards 3.0, pushing only 3.0
  fast-forwards main, and a diverged pair fails the run without moving either side
  (verified by local simulation)