From e3fc99efc94e3f4dae61cd365d26fcd441d1f307 Mon Sep 17 00:00:00 2001 From: "ren.ji" Date: Mon, 12 Oct 2026 19:39:14 +0800 Subject: [PATCH] docs: pin downstream Rivet installations --- CHANGELOG.md | 3 +++ docs/ci.md | 43 ++++++++++++++++++++++++++++------------- docs/ci.zh-CN.md | 35 ++++++++++++++++++++++++--------- tests/documentation.rkt | 12 ++++++++++++ 4 files changed, 71 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 35fdd93..46bfd1b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ ## Unreleased +- Document one reproducible downstream install contract: pin Rivet's Git + package source and `setup-embed-racket` action to the same revision, and + install the package only after the minimal embeddable runtime is active. - Bound and retry Ubuntu runner package-manager operations so a stalled mirror cannot consume an entire desktop validation job without a useful failure. - Removed the misleading `rivet-type` runtime descriptors from the pre-1.0 diff --git a/docs/ci.md b/docs/ci.md index e4be42e..6f15007 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -22,9 +22,10 @@ release environment. ## Copy-paste GitHub Actions workflow -The following workflow assumes the application installs the released `rivet` -package from the Racket Package Catalog. Pin the Racket and Rivet versions used -by production instead of allowing the two workflows to drift. +The following workflow pins Rivet 0.7.0. Update every Rivet package source and +the Linux setup action to the same tag (or full commit) in one review. A direct +Git source is intentional: the Racket Package Catalog has one current entry +for a package name and cannot select an older Rivet release. ```yaml name: Native hosts @@ -48,7 +49,7 @@ jobs: distribution: full variant: CS version: '9.3' - - run: raco pkg install --auto --no-docs rivet + - run: raco pkg install --auto --no-docs 'https://github.com/turinglambdaai/rivet.git#v0.7.0' - run: raco rivet doctor - run: raco rivet schema check rivet-schema.json - run: raco rivet build @@ -67,7 +68,7 @@ jobs: distribution: full variant: CS version: '9.3' - - run: raco pkg install --auto --no-docs rivet + - run: raco pkg install --auto --no-docs 'https://github.com/turinglambdaai/rivet.git#v0.7.0' - run: raco rivet doctor - run: raco rivet schema check rivet-schema.json - run: raco rivet build @@ -77,17 +78,34 @@ jobs: steps: - uses: actions/checkout@v7 - name: Set up embeddable Racket CS - uses: turinglambdaai/rivet/.github/actions/setup-embed-racket@main + uses: turinglambdaai/rivet/.github/actions/setup-embed-racket@v0.7.0 - name: Install GTK4 development files run: | sudo apt-get update sudo apt-get install --yes libgtk-4-dev - - run: raco pkg install --auto --no-docs rivet + - name: Install the matching Rivet package and dependencies + run: raco pkg install --auto --no-docs 'https://github.com/turinglambdaai/rivet.git#v0.7.0' - run: raco rivet doctor - run: raco rivet schema check rivet-schema.json - run: raco rivet build ``` +The Linux order is load-bearing: install the Rivet package **after** +`setup-embed-racket`. The action's minimal Racket build intentionally ships +without packages; installing Rivet afterward resolves `cext-lib`, `crypto-lib`, +`keel`, and the rest of the dependency closure into the package directory that +the embeddable runtime actually uses. Installing Rivet earlier under a full +Racket distribution can make those dependencies appear satisfied there while +leaving the minimal runtime incomplete; a later backend bundle then fails, for +example because `raco ctool` is supplied by `cext-lib`. + +For an intentionally moving development channel, replace the direct Git source +with the catalog name `rivet` and use the setup action from `@main`. Do not use +that pair as a release pin: catalog installation follows the catalog's current +checksum and there is no `raco pkg install rivet@` selector. The +standard hold-back form is the tag-pinned Git source shown above. Racket treats +the fragment as the Git revision while retaining normal dependency resolution. + Rivet itself additionally launches the generated GTK4 package inside a headless Weston compositor with `GDK_BACKEND=wayland`. This is a native Wayland gate: `DISPLAY` is unset, so the application cannot silently pass by @@ -109,18 +127,17 @@ close while retaining bounded failure evidence. See [native UI end-to-end testing](native-ui-testing.md) for the application-level extension contract. -For a security-sensitive product, replace `@main` with the Rivet tag or full -commit SHA used by the application. The action downloads the official minimal +For a security-sensitive product, replace the action tag with the full commit +SHA for that tag and use the same commit in the package URL fragment. The action downloads the official minimal Racket CS source archive, verifies its SHA-256, builds and caches the static embedding runtime by version/OS/architecture, and exports `RIVET_RACKET_INCLUDE`, `RIVET_RACKET_LIB_DIR`, `RIVET_RACKET_LIBRARY`, and `RIVET_RACKET_BOOT_DIR`. Product workflows should not copy those discovery rules. -If an application installs Rivet from a linked or Git checkout rather than the -catalog, pin that checkout and the setup action to the same revision. A host -compiled against one Rivet revision and released with another is not a useful -gate. +For local Rivet development, a linked checkout remains appropriate. Pin that +checkout and the setup action to the same revision in CI. A host compiled +against one Rivet revision and released with another is not a useful gate. ## Release gate diff --git a/docs/ci.zh-CN.md b/docs/ci.zh-CN.md index 9ed4cdb..7a7eb17 100644 --- a/docs/ci.zh-CN.md +++ b/docs/ci.zh-CN.md @@ -19,8 +19,10 @@ CI 应使用与发布任务相同类别的 runner 和工具链： ## 可直接使用的 GitHub Actions 工作流 -下面的工作流假设应用从 Racket Package Catalog 安装已发布的 `rivet` 包。 -生产项目应固定 Racket 与 Rivet 版本，不能让 CI 和发布任务各自漂移。 +下面的工作流固定到 Rivet 0.7.0。升级时，应在同一次评审中把每处 Rivet +包来源和 Linux setup action 更新到同一个标签（或完整 commit）。这里有意 +使用 Git 来源：Racket Package Catalog 对每个包名只保留一个当前入口，不能 +选择较旧的 Rivet 版本。 ```yaml name: Native hosts @@ -44,7 +46,7 @@ jobs: distribution: full variant: CS version: '9.3' - - run: raco pkg install --auto --no-docs rivet + - run: raco pkg install --auto --no-docs 'https://github.com/turinglambdaai/rivet.git#v0.7.0' - run: raco rivet doctor - run: raco rivet schema check rivet-schema.json - run: raco rivet build @@ -63,7 +65,7 @@ jobs: distribution: full variant: CS version: '9.3' - - run: raco pkg install --auto --no-docs rivet + - run: raco pkg install --auto --no-docs 'https://github.com/turinglambdaai/rivet.git#v0.7.0' - run: raco rivet doctor - run: raco rivet schema check rivet-schema.json - run: raco rivet build @@ -73,25 +75,40 @@ jobs: steps: - uses: actions/checkout@v7 - name: Set up embeddable Racket CS - uses: turinglambdaai/rivet/.github/actions/setup-embed-racket@main + uses: turinglambdaai/rivet/.github/actions/setup-embed-racket@v0.7.0 - name: Install GTK4 development files run: | sudo apt-get update sudo apt-get install --yes libgtk-4-dev - - run: raco pkg install --auto --no-docs rivet + - name: Install the matching Rivet package and dependencies + run: raco pkg install --auto --no-docs 'https://github.com/turinglambdaai/rivet.git#v0.7.0' - run: raco rivet doctor - run: raco rivet schema check rivet-schema.json - run: raco rivet build ``` -对安全要求高的产品，应把 `@main` 改成应用使用的 Rivet 标签或完整 commit -SHA。该 action 会下载官方 minimal Racket CS 源码归档、校验 SHA-256、按 +Linux 中的顺序是必要条件：必须在 `setup-embed-racket` **之后**安装 Rivet。 +该 action 准备的是刻意不附带任何包的 minimal Racket；此时再安装 Rivet， +`cext-lib`、`crypto-lib`、`keel` 等完整依赖才会进入嵌入式 runtime 实际读取的 +包目录。如果先在 full Racket 下安装，这些依赖可能在那里显示为已满足，却没有 +进入 minimal runtime；之后制作 backend bundle 就会失败，例如 `raco ctool` +实际由 `cext-lib` 提供。 + +若明确需要随开发分支移动，可把 Git 来源换回 catalog 包名 `rivet`，并把 setup +action 改为 `@main`。不要把这组配置当作发布版本固定：catalog 安装跟随当前 +checksum，也不存在 `raco pkg install rivet@` 这种历史版本选择器。 +标准的版本保留方式就是上面带标签的 Git 来源；Racket 会把片段解释为 Git +revision，同时照常解析依赖。 + +对安全要求高的产品，应把 action 标签换成该标签对应的完整 commit SHA，并在 +包 URL 片段中使用同一个 commit。该 action 会下载官方 minimal Racket CS +源码归档、校验 SHA-256、按 版本/系统/架构构建并缓存静态嵌入 runtime，然后导出 `RIVET_RACKET_INCLUDE`、`RIVET_RACKET_LIB_DIR`、 `RIVET_RACKET_LIBRARY` 和 `RIVET_RACKET_BOOT_DIR`。产品工作流不应再复制 这套探测脚本。 -若应用安装的是 link 或 Git checkout 版本的 Rivet，应让 checkout 与 setup +本地开发 Rivet 时仍适合使用 link checkout；在 CI 中应让 checkout 与 setup action 固定到同一 revision。用一个 Rivet revision 编译宿主、再用另一个 revision 发布，不构成有效门禁。 diff --git a/tests/documentation.rkt b/tests/documentation.rkt index 5f3b69a..0392688 100644 --- a/tests/documentation.rkt +++ b/tests/documentation.rkt @@ -129,6 +129,18 @@ "raco rivet build"))]) (check-file-contains ci-guide expected)) (check-file-contains ci-guide-zh "raco rivet build") +(for ([guide (in-list (list ci-guide ci-guide-zh))]) + (check-file-contains + guide + "https://github.com/turinglambdaai/rivet.git#v0.7.0") + (check-file-contains guide "setup-embed-racket@v0.7.0") + (define text (file->string guide)) + (check-true + (regexp-match? + #px"(?s:linux-host:.*setup-embed-racket@v0[.]7[.]0.*raco pkg install.*rivet[.]git#v0[.]7[.]0)" + text) + (format "~a must install the pinned package after the embeddable runtime" + (find-relative-path repository-root guide)))) (define embed-action (build-path repository-root ".github" "actions" "setup-embed-racket" "action.yml"))