Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
77 commits
Select commit Hold shift + click to select a range
02334f6
fix: a resource script compiles with its package's include_dirs expan…
Sunrisepeak Nov 20, 2026
e941e6c
fix: the resource include list is a function of its own (step13_windo…
Sunrisepeak Nov 20, 2026
94e8193
docs: the test and CI design for mtest, mcpp's test system and CI (mc…
Sunrisepeak Nov 20, 2026
d82e2d9
fix: a resource script's include dirs are expanded as the root manife…
Sunrisepeak Nov 20, 2026
7ae560a
fix: a package's instance is a function of its configuration, not of …
Sunrisepeak Nov 20, 2026
2277ffc
feat: a test and a build share the machine's budget of slots and a me…
Sunrisepeak Nov 20, 2026
25700dd
feat: a run records its machine, each case's processor time, steps, i…
Sunrisepeak Nov 20, 2026
682afda
feat: a build records each edge it ran with its processor time and la…
Sunrisepeak Nov 20, 2026
8bf0bb9
chore: mcpplibs.mtest 0.11.0 and mcpplibs.os 0.4.7 throughout, the sk…
Sunrisepeak Nov 20, 2026
f7d3a16
feat: the dependencies from the store and git compile with the line t…
Sunrisepeak Nov 20, 2026
44f8275
feat: a package whose sources are named runs its build program in the…
Sunrisepeak Nov 20, 2026
aa9af7a
test: a program run through wine returns when wine's services have ended
Sunrisepeak Nov 20, 2026
31dbf2b
feat: a compile whose command and read files hold an earlier compile'…
Sunrisepeak Nov 20, 2026
36b98a0
feat: the split schedule's units are placed from the unit cache too; …
Sunrisepeak Nov 20, 2026
47cefb2
fix: a compile the executor did not keep leaves no producer key besid…
Sunrisepeak Nov 20, 2026
fbc2e4c
mcpp emit surface; an invocation records the items it used (design 20…
Sunrisepeak Nov 20, 2026
41e79b4
mcpp test serves run fixtures (SPEC-017 P11, design 2026-11-20 §5.10)
Sunrisepeak Nov 20, 2026
e71fa6d
--since: a header affects the tests built from the units that read it…
Sunrisepeak Nov 20, 2026
7c618f2
SPEC-004 §9 items 17 to 20; SPEC-017 O6 and the surface; features for…
Sunrisepeak Nov 20, 2026
e10d52f
The test kit: surface items, the shared home as a run fixture, homes …
Sunrisepeak Nov 20, 2026
6e9ff7f
docs: memory_threshold, dependency_debug, the run's records, one budg…
Sunrisepeak Nov 20, 2026
e397c96
The dependency_debug comment is shorter: toolchain.cpp stays within 2…
Sunrisepeak Nov 20, 2026
9d6806a
CI: a tree is verified once, and a release promotes the archives a ru…
Sunrisepeak Nov 20, 2026
16cde79
mtest 0.11.1 throughout, and CI's engine with it (a command an e2e ca…
Sunrisepeak Nov 20, 2026
4d4c2fc
design 2026-11-20 §14: the record of the implementation -- repositori…
Sunrisepeak Nov 20, 2026
0e10735
design 2026-11-20 §14: the coverage tables stay with check_e2e_covera…
Sunrisepeak Nov 20, 2026
0aef472
docs/08: the downstream action project-test
Sunrisepeak Nov 20, 2026
bb94dab
The build record states an edge that copied a unit of a package the c…
Sunrisepeak Nov 20, 2026
c14b434
CI: a consumer of this commit's mcpp reads the current index's recipe…
Sunrisepeak Nov 20, 2026
29f7ddf
design 2026-11-20 §14: the index the fix needs, and the record's stag…
Sunrisepeak Nov 20, 2026
f81f153
2026.11.21.1
Sunrisepeak Nov 20, 2026
15e4cfa
CI: the macOS e2e suite runs on the newest image at a checkpoint (ful…
Sunrisepeak Nov 20, 2026
268cbf8
CI: e2e-cases prints the run's records when a program fails beside it…
Sunrisepeak Nov 20, 2026
beb7243
mcpp test: a worker that waits for a slot gives up once no test is le…
Sunrisepeak Nov 21, 2026
1705f22
The unit cache records what a Clang compile read: its depfile names t…
Sunrisepeak Nov 21, 2026
159edcc
A build program run in a packing pass runs in the project: its output…
Sunrisepeak Nov 21, 2026
d91550e
memory_threshold enters the grouping key of a plan's members, as jobs…
Sunrisepeak Nov 21, 2026
efc91d1
The kit initializes a case's inherited home with the real xlings; the…
Sunrisepeak Nov 21, 2026
cf2d875
An invocation records the root's flags read before the parser (--no-c…
Sunrisepeak Nov 21, 2026
cb1679e
mcpp index list names the registries mcpp index add added (the provid…
Sunrisepeak Nov 21, 2026
f017e14
e2e: the maintenance commands and a test run's selection flags no oth…
Sunrisepeak Nov 21, 2026
380e8c7
design 2026-11-20 §14: the first checkpoint's findings and the surfac…
Sunrisepeak Nov 21, 2026
854fde1
tests: the default toolchain of the host installs where gcc is absent…
Sunrisepeak Nov 21, 2026
95ecf49
design 2026-11-21: a build program's inputs are observed, notices hav…
Sunrisepeak Nov 21, 2026
8ebf07e
design 2026-11-21: offline, host inputs and toolchain defaults (mcpp#…
Sunrisepeak Nov 21, 2026
1e6a151
design 2026-11-21: the second sub-design confirmed; an @ reference is…
Sunrisepeak Nov 21, 2026
2c8c322
design records: decisions stated with their dates; one mechanism per …
Sunrisepeak Nov 21, 2026
da55a94
design 2026-11-21: a library loaded with dlopen is reachable as the r…
Sunrisepeak Nov 21, 2026
c3f3a74
mcpp.notice: the policies of user-visible notices and a project's rec…
Sunrisepeak Nov 21, 2026
49e6807
diag: every warning, note and closing tip goes through mcpp.diag
Sunrisepeak Nov 21, 2026
f5eb24d
build programs: the files a compile read are inputs of all three gate…
Sunrisepeak Nov 21, 2026
6a051ba
build programs' inputs: tests, SPEC-007 R10.3 and R10.8 to R10.10, do…
Sunrisepeak Nov 21, 2026
9352b38
toolchain identification and the command line's @ (mcpp#989; design 2…
Sunrisepeak Nov 21, 2026
1732bbf
toolchain: one resolution of a request, the lock of a stated partial …
Sunrisepeak Nov 21, 2026
0ffcb46
runtime: a required dlopen library is judged from the object that loa…
Sunrisepeak Nov 21, 2026
dd05a8d
host inputs: [build] allow_host_tools states a host bootstrap tool, a…
Sunrisepeak Nov 21, 2026
bd33671
offline: mcpp fetch writes a project's inputs into a directory and ta…
Sunrisepeak Nov 21, 2026
0ec1208
defaults: the first run's toolchain and the bootstrap tools are [[def…
Sunrisepeak Nov 21, 2026
a7c7cb0
package features as machine-readable answers (mcpp#992); a cached ent…
Sunrisepeak Nov 21, 2026
b7c8954
test protocol: what a scope's body does is the program's (SPEC-017 P5…
Sunrisepeak Nov 21, 2026
9ba23e2
notices: a command that plans in a directory of its own reads the pro…
Sunrisepeak Nov 21, 2026
11a6f73
test runner: a worker that waits for the machine gives its budget slo…
Sunrisepeak Nov 21, 2026
7f205aa
tests: the build commands' shared flags and the [build] keys no other…
Sunrisepeak Nov 21, 2026
6f25fd7
system names: the offline refusal names the host's first run from its…
Sunrisepeak Nov 21, 2026
2b308f6
defaults: gcc 16.2.0 (Linux x86_64, Windows without MSVC, the MinGW r…
Sunrisepeak Nov 21, 2026
c25190c
paths in the manifest's and the bundle's messages and git arguments a…
Sunrisepeak Nov 21, 2026
a7459fd
upgrade lane: an upgraded home's first run takes the bootstrap tools …
Sunrisepeak Nov 21, 2026
2a6b141
tests: a graph's libstdc++ package states its link directory (934); t…
Sunrisepeak Nov 21, 2026
be6f33e
upgrade lane: a served dependency BMI is found under either staging d…
Sunrisepeak Nov 21, 2026
96cb914
provider: a compiler's baked sysroot of subos/current is the building…
Sunrisepeak Nov 21, 2026
f692832
tests: a GCC named by path states its assembler (925); the fake xling…
Sunrisepeak Nov 21, 2026
42ebd05
a refusal without a token is reported as other by every why output (t…
Sunrisepeak Nov 21, 2026
e7bff05
tests: the kit records every mcpp command it composes and states the …
Sunrisepeak Nov 21, 2026
be6ec3c
upgrade lane: the cache's spelling moved in 2026.11.21.1 (an instance…
Sunrisepeak Nov 21, 2026
7837336
matrix scan: a failed cell's report keeps each error's indented conti…
Sunrisepeak Nov 21, 2026
1eb7de1
a GCC named by path compiles and links with the binutils its project …
Sunrisepeak Nov 21, 2026
c52004d
tests: 860 holds that more than one compile is under way at -j 4 and …
Sunrisepeak Nov 21, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
1,009 changes: 1,009 additions & 0 deletions .agents/docs/2026-11-20-test-architecture-upgrade-design.md

Large diffs are not rendered by default.

332 changes: 332 additions & 0 deletions .agents/docs/2026-11-21-build-program-observed-inputs-design.md

Large diffs are not rendered by default.

Large diffs are not rendered by default.

108 changes: 108 additions & 0 deletions .agents/docs/2026-11-21-package-features-query-design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
---
subject: ecosystem
status: active
---

# 包的特性作为机器可读的回答:一个目录项,两种来源,三种状态(mcpp#992)

**日期:** 2026-11-21 · **版本:** v1 · **基线:** mcpp 2026.11.21.1 的分支(#984) · **规范:** SPEC-001 §3.5(描述符的两种形式)、
SPEC-004(清单的键)、SPEC-010 §5(只读查询不安装)、docs/50(`kindVersion` 内只增加字段) · **所属:**
[生态的测试与 CI 方案](2026-11-20-test-architecture-upgrade-design.md) 第 15 节的子方案三。

## 1. 问题

mcpp-ide 只显示 mcpp 陈述的事实,不读索引的描述符(mcpp-ide#16、#17:`features = [...]` 中的补全、悬停、未知名字的诊断、
包详情中的勾选)。mcpp 的机器输出不含包的特性:`mcpp search --format json` 只有 `description`、`id`、`index`、`licenses`、
`name`、`namespace`、`repo`、`versions`;`mcpp xpkg parse` 与 `mcpp why` 也没有。

## 2. 现状的测量

- **一个模型。** `mcpp.toml`(`toml.cppm`)与描述符的内联表(`xpkg.cppm` 的 `synthesize_from_xpkg_lua`)解析到同一个
`Manifest`:`featuresMap`(特性 → implies,`default` 项为缺省集合)、`featureForwards`(`<依赖>/<特性>`)、
`featureRequires`、`featureProvides`。不需要新的读取。
- **两种来源。** 本机 mcpplibs 索引的 342 个描述符中,197 个为内联形式,特性在索引中(30 个写有特性);81 个为指针形式、
66 个未写 `mcpp` 字段(按约定为指针形式),共 147 个,特性在载荷的 `mcpp.toml` 中。内联表对描述符的所有版本共用;
指针形式的每个版本各有自己的清单。
- **读取路径已经收敛。** `mcpp.pm.descriptor` 的 `descriptor_payload_present` 判断载荷是否在,`descriptor_manifest` 给出
内联表或载荷中清单的位置(mcpp#960)。构建在读取指针形式的清单时另做一步:归档中的 workspace 成员接受其 workspace
的继承(`graph_load` 的 `loadFrom`)。
- **没有描述。** 两种来源都没有特性的 `description`;表形式的键检查(#540)把它报为未知键。

## 3. 决定

### 3.1 一个目录项

`mcpp.manifest` 增加 `feature_catalog(const Manifest&)`:每个特性一项,`name`、`default`(在缺省集合中)、`implies`
(本包的特性)、`enables`(`<依赖>/<特性>`)、`description`(可空),按名字排序;`default` 本身不是一项。所有输出由它给出,
JSON 的形状只在一处写出。

### 3.2 一条读取路径

`mcpp.pm.package_manifest` 的 `installed_manifest` 给出索引包某个已安装版本的清单:`descriptor_manifest` 之后,指针形式的
清单按构建的方式读取,含归档中 workspace 的继承与描述符的命名空间。构建(`graph_load`)与查询都调用它,二者对同一个包不会
给出不同的特性。`workspace_listing` 与 `inherit_as_workspace_member` 由 prepare 移入该模块;错误是 `ManifestError`
(`at` 为读不出的清单),由调用方以自己的主语写出,构建的消息不变。

### 3.3 三种状态

一个包的一个版本的回答:

```json
"features": {
"version": "0.0.5",
"state": "declared",
"from": "payload",
"list": [ { "name": "gui", "default": true, "implies": ["render"], "enables": ["imgui/docking"],
"description": "..." } ]
}
```

| `state` | 含义 | `list` |
|---|---|---|
| `declared` | 回答取自索引(内联形式)或已安装的载荷中的清单 | 特性的列表,没有特性时为 `[]` |
| `not-installed` | 指针形式,该版本的载荷不在 store 中 | `null` |
| `unreadable` | 载荷在,清单读不出;另附一条诊断 | `null` |

`[]` 只表示「声明了零个特性」。未知的回答为 `null`:只读列表的客户端若把未安装读成没有特性,会把每个合法的名字诊断为
未知。`from` 为 `index` 或 `payload`。

不是 mcpp 包的条目不输出 `features`。判据取自已有的两个事实:描述符写有 `mcpp` 字段(任一形式)的是 mcpp 包;不写该字段的
描述符,在提供方的官方索引(`official_index_status` 的目录)中是提供方自身的载荷,在其他索引中按 SPEC-001 §3.5 的约定为
指针形式。本机的目录中,官方索引的 342 个 `xim` 条目与 `luban` 等命名空间的条目不输出;mcpplibs 索引的 66 个未写字段的
描述符按指针形式回答。

### 3.4 不安装

查询不下载、不安装(SPEC-010 §5):已安装就读取,未安装就以 `not-installed` 回答。取得载荷的是构建与 `mcpp fetch`。

### 3.5 两个输出

- **`mcpp search --format json`**:每个包的 `features`,为最新版本(`versions` 的第一项)的回答。一个包的查询即精确名字的
search。`mcpp.search` 的 `kindVersion` 保持 1(只增加字段)。
- **`mcpp why features [--format json]`**(`mcpp.why.features`):本工程解析出的每个包,`package`、`root`(是否为根)、
`manifest_dir`,以及 `features` 的 `list` 与 `active`(本次构建激活的特性)。规划时每个包都已在 home 中,列表总是已知的。
数据记录在 `resolution.json` 的 `graph` 中(`features` 为激活的特性,与构建程序读取的图文档同名同形;`feature_list`
为目录项),命令读取该记录,与 `mcpp why deps` 读取同一记录相同。构建程序的图文档不加目录项:它是构建程序重跑键的一部分,
描述的改动不应使构建程序重跑。不给话题的 `mcpp why` 不含该话题,与 `flags`、`platform` 相同。

`--protocol-version` 的 `features` 增加 `package-features`。

### 3.6 描述

表形式的特性增加 `description`(字符串),与 `[package] description` 同名同义;描述符的内联表的特性项同样接受。
短形式(`x = ["a"]`)没有描述。键检查的已知键随之增加。

## 4. 不做的

- 不在发布时把特性抄进指针形式的描述符:两份事实会分离,描述符也不按版本区分。
- 不在查询中取得载荷。

## 5. 验证

| # | 判据 | 层 | 用例 |
|---|---|---|---|
| Q1 | `feature_catalog` 的缺省(含闭包)、implies、enables、description 与排序 | 单元 | `FeatureCatalog/*`(modules/manifest) |
| Q2 | `description` 在两种来源中被读取且为字符串,表形式不再报未知键;两种来源对同一陈述给出同一目录 | 单元 | `FeatureCatalog/*` |
| Q3 | 三种状态:内联形式为 `declared`/`index`;指针形式已安装为 `declared`/`payload`(含归档中 workspace 的继承),未安装为 `not-installed`,清单读不出为 `unreadable`,后两者 `list` 为 `null` | 单元、e2e | `PackageFeatures/*`;`index::features/992 …never installed`(search 前后各一次,中间以 `mcpp fetch` 安装) |
| Q4 | `mcpp why features`:路径依赖的 `list`、`active` 与描述,JSON 与文本 | e2e | `index::features/992 why features…` |
| Q5 | `--protocol-version` 列出 `package-features` 与 `mcpp.why.features` | e2e | `cli::golden/1123` |
13 changes: 12 additions & 1 deletion .agents/docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ superseded_by: 2026-09-07-....md # when status is superseded
---
```

367 records.
371 records.

## By subject

Expand All @@ -36,6 +36,7 @@ Records that declare one. Everything else is listed by date below.

### build-program

- [构建程序的输入由观测给出:编译读到的文件、三道闸门的同一份记录、头文件的用法提示、提示的统一机制、契约中名字的歧义(mcpp#991、#852)](2026-11-21-build-program-observed-inputs-design.md) — active
- [构建依赖的一条管线:配置与产物两轴、包的实例、库接口、兼容系统与工作空间收尾(#797)](2026-10-11-build-dependencies-one-pipeline-design.md) — active
- [Four upstream asks from a UI framework: what each one is under mcpp's design, and the combined plan](2026-09-13-four-upstream-asks-from-a-ui-framework.md) — landed

Expand Down Expand Up @@ -91,6 +92,8 @@ Records that declare one. Everything else is listed by date below.

### ecosystem

- [包的特性作为机器可读的回答:一个目录项,两种来源,三种状态(mcpp#992)](2026-11-21-package-features-query-design.md) — active
- [离线、宿主输入与工具链的缺省:按内容取归档的来源、项目的取齐、宿主输入的声明、工具链的解析与锁、缺省版本的规则(mcpp#988、#989、#990)](2026-11-21-offline-host-inputs-and-toolchain-defaults-design.md) — active
- [生态规则收敛方案:2026.11.18.1 之后十个 issue 的五类成因、七项决定与实施范围](2026-11-19-ecosystem-rule-convergence-design.md) — landed
- [生态架构优化方案:四个平面的收敛、已合入项的纠正与新系统的准入(mcpp × openkal × xlings)](2026-11-12-ecosystem-architecture-optimization-design.md) — active
- [测试与依赖解析补充方案:mcpp、mcpp test、mtest、mcpp-ide](2026-11-10-test-and-resolution-supplement-design.md) — active
Expand Down Expand Up @@ -173,6 +176,10 @@ Records that declare one. Everything else is listed by date below.
- [SDK toolchains, the payload/engine seam, and openkal across iOS, Android and Web](2026-09-11-sdk-toolchains-and-ios-local-verification.md) — landed
- [Where a platform's knowledge belongs: iOS, Android and Web across the engine, the index and the plugins](2026-09-11-platform-targets-design-review.md) — active

### test

- [生态的测试与 CI 方案:mtest 的框架与运行控制、mcpp 自身的测试系统、CI 的形态(mcpp#986、#976、#927、#802)](2026-11-20-test-architecture-upgrade-design.md) — active

### toolchain

- [目标基座与执行宿主:sysroot 的通用模型、运行器契约、自备输入,以及同批的发布产物路径(#832)](2026-10-23-target-base-and-execution-host-design.md) — landed
Expand Down Expand Up @@ -206,6 +213,10 @@ Records that declare one. Everything else is listed by date below.

### 2026-11

- [包的特性作为机器可读的回答:一个目录项,两种来源,三种状态(mcpp#992)](2026-11-21-package-features-query-design.md) — active
- [离线、宿主输入与工具链的缺省:按内容取归档的来源、项目的取齐、宿主输入的声明、工具链的解析与锁、缺省版本的规则(mcpp#988、#989、#990)](2026-11-21-offline-host-inputs-and-toolchain-defaults-design.md) — active
- [构建程序的输入由观测给出:编译读到的文件、三道闸门的同一份记录、头文件的用法提示、提示的统一机制、契约中名字的歧义(mcpp#991、#852)](2026-11-21-build-program-observed-inputs-design.md) — active
- [生态的测试与 CI 方案:mtest 的框架与运行控制、mcpp 自身的测试系统、CI 的形态(mcpp#986、#976、#927、#802)](2026-11-20-test-architecture-upgrade-design.md) — active
- [程序起点模型:启动者、两层入口与 `main` 的三种陈述(mcpp#845、mcpp#981)](2026-11-20-program-start-model.md) — landed
- [生态规则收敛方案:2026.11.18.1 之后十个 issue 的五类成因、七项决定与实施范围](2026-11-19-ecosystem-rule-convergence-design.md) — landed
- [第二部分之后的补充方案:带修正的 ninja、模块重编译的级联、工作区发布与本轮遗留项](2026-11-17-ninja-cascade-publish-supplement-design.md) — active
Expand Down
22 changes: 22 additions & 0 deletions .agents/skills/mcpp-contributing/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,19 @@ E2E 并不保证完全离线:部分脚本需要工具链、索引或 capabilit
按 CI 等价方式设置 `MCPP_HOME`、镜像和其他 capability 后再运行;不要让缓存命中
或空 workspace 选择冒充行为覆盖。

C++ 端到端用例的写法(`tests/support`,设计 2026-11-20):

- 等待被测程序给出的事件(一行输出、一个文件、退出),不等待时间;`sleep_for` 与 shell `sleep <n>` 的次数只减不增
(`.github/tools/check_waits.sh`、`waits.baseline`)。只为改变修改时间的等待改用 `s::touch(file)`。
- 断言只在其 home 不被别人改写时成立的用例(回放的构建、快速路径)调用 `s::own_home()`,在自己的 home 中运行 mcpp,
而不持有 `machine`;改写 home 配置的用例写自己 home 的 `config.toml`,不写共享 home 的。
- 继承的 home(`home::inherited`、`_inherit_toolchain.sh`)以用户的 home 为 upstream,不链接其载荷,不复制 subos。
- 每个 E2E 组带 `s::home_fixture`:共享的 home 是运行夹具,其填充记在夹具上。
- 形式本身是契约的输出(`--protocol-version`、`emit surface`)以 golden 文件整段比较;改变它的拉取请求以
`MTEST_GOLDEN=update` 更新文件,审阅读取更新给出的改动。
- 程序写出的 `warning:` 与 `error:` 行由用例以 `e2e::expect_diagnostic` 声明;kit 以 `report` 方式统计未声明的行。
- 不变量(无改动的重建、第二个工程)以构建记录(`MCPP_BUILD_RECORD`)计数,以指标与界限陈述。

### 4. 提交 PR

**提交信息前缀**:`feat:` / `fix:` / `refactor:` / `test:` / `docs:` / `chore:`
Expand Down Expand Up @@ -357,6 +370,15 @@ UTF-8 ACP(65001),这类用例会静默变成永远绿的装饰品。参见
「只有它自己和它声明的依赖」这个配置里——那是根构建从不产生的配置,也是唯一
能抓到「悄悄依赖了未声明之物」的地方。
⚠️ `mcpp test -p <x>` 对没有测试的成员**退 0**
- **用户可见的提示只有一个汇点 `mcpp.diag`**:`warning`、`degraded`、`note`、`notice`
与收尾的 `closing`/`on_failure`。`mcpp::ui::warning`、`note`、`tip` 只由 `mcpp.diag`
渲染使用,其他地方直接调用或向 stderr 写 `warning:`/`note:`/`tip:` 都由
`.github/tools/check_diag_sink.sh` 在 CI 中拒绝。领域即代码:`build-program/reads-outside`
在机器输出中是 `MCPP_BUILD_PROGRAM_READS_OUTSIDE`
- **策略不是缺省(每次都说)的提示先登记**:`modules/notice` 的 `kKinds` 一行陈述领域、
策略(`once`:一个工程每个对象只说一次,记在 `target/.mcpp-notices`)与文档位置,调用
`mcpp::diag::notice(..., subject, ...)`;多个对象合并为一条时用带 `scope` 与对象列表的形式。
改变这次构建结果的事实(降级、弃用的读法、未知的键)不登记为 `once`
- E2E 测试应声明所需 capability,并使用隔离的 `MCPP_HOME`;需要网络/索引的脚本
不得被描述为完全离线
- 不确定方向时先在 Issue 讨论再动手
Expand Down
34 changes: 26 additions & 8 deletions .agents/skills/mcpp-release/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,14 @@ git checkout main && git pull origin main
gh run list --branch main --limit 3
```

缺省版本与索引比对(docs/51「缺省版本」):每个 `[[default]]` 应为上游最新的正式发布。
`behind` 的一项在发版前移动(载荷先进入 xim-pkgindex),或在 CHANGELOG 中陈述保留的原因;
上游的发布页另行核对,索引可能落后于上游。

```bash
bash .github/tools/check_defaults.sh <xim-pkgindex checkout>
```

以分支保护和 `gh pr checks <pr-number>` 显示的 actual required checks 为准。
在 main 上监控当前运行时,检查 `ci` 这一个工作流的运行(它包含各平台、e2e 分片、
交叉构建与 `e2e-coverage`);known-red 的腿(名字里带 issue 号)允许失败。跳过或
Expand Down Expand Up @@ -108,28 +116,38 @@ gh pr create --title "chore: bump version to $NEW_VERSION" --body "..."
然后推送(标签在 push 启动运行时读取)。这样 PR 自己的运行就是全集,结果在 PR 的检查中可见。不要以
`gh workflow run ci.yml --ref <分支>` 另开一次运行,也不要取消 PR 的运行(见 mcpp-contributing 第 5 节)。

全集运行通过时留下 `verified-<tree>`(设计 2026-11-20 §5.22),它的 `release-form` 作业留下四个发布归档。
版本号的两处、CHANGELOG 与文档中 `@NEXT@` 的替换都在这次运行之前提交:之后的任何改动都改变树,标记随之失效。
合入(squash)之后 main 的树与被验证的树相同,main 的运行只登记、保存缓存,不再运行测试,**不取消它**。
合入与打 tag 之间 main 移动过时,发布照常构建,摘要写明原因。

### 3. 创建并推送 tag

```bash
git tag "v$NEW_VERSION"
git push origin "v$NEW_VERSION"
```

Tag push 会自动触发 `release.yml` workflow。
Tag push 会自动触发 `release.yml` workflow。它的 `find` 作业由 tag 得到树:有运行验证过这棵树、且仍保留
四个 `release-*` 归档(七天)时,`promote` 提升它们(核对 `.sha256` 与 Linux 程序报告的版本),不再构建;
否则运行 `release-build.yml` 的四个构建。运行摘要写明 "Promoted" 或 "Built" 及原因。

### 4. 监控 Release CI

Release workflow 的四个平台构建**同时开始**,各自把归档留作 artifact;`create-release`
在四个构建都通过后一次创建带全部归档的 GitHub release(设计 2026-11-14):
Release workflow 先由 `find` 决定提升还是构建。构建时四个平台构建(`release-build.yml`)**同时开始**,
各自把归档留作 artifact;`create-release` 在四个构建或 `promote` 通过后一次创建带全部归档的 GitHub
release(设计 2026-11-14、2026-11-20 §5.22):

| Job | 平台 | 产物 | 依赖 |
|-----|------|------|------|
| `canaries` | — | 生态项目(xlings、mcppls)用候选版本构建 | 仅手动发布且勾选 `canaries` 时运行 |
| `build-release` | Linux x86_64 | `mcpp-X.Y.Z-linux-x86_64.tar.gz`、源码包、`mcpp.lua`、`install.sh` | 无 |
| `build-linux-aarch64` | Linux aarch64(交叉) | `mcpp-X.Y.Z-linux-aarch64.tar.gz` | 无 |
| `build-macos` | macOS ARM64 | `mcpp-X.Y.Z-macosx-arm64.tar.gz` | 无 |
| `build-windows` | Windows x86_64 | `mcpp-X.Y.Z-windows-x86_64.zip` | 无 |
| `create-release` | — | GitHub release、覆盖全部归档的 `SHA256SUMS` | 四个构建(及运行时的 canaries) |
| `find` | — | tag、提交、树与验证它的运行 | 无 |
| `promote` | — | 被验证运行的四个归档,作为 `release-promoted` | `find` 找到运行时 |
| `build-release` | Linux x86_64 | `mcpp-X.Y.Z-linux-x86_64.tar.gz`、源码包、`mcpp.lua`、`install.sh` | `find` 未找到运行时(`build`) |
| `build-linux-aarch64` | Linux aarch64(交叉) | `mcpp-X.Y.Z-linux-aarch64.tar.gz` | `find` 未找到运行时(`build`) |
| `build-macos` | macOS ARM64 | `mcpp-X.Y.Z-macosx-arm64.tar.gz` | `find` 未找到运行时(`build`) |
| `build-windows` | Windows x86_64 | `mcpp-X.Y.Z-windows-x86_64.zip` | `find` 未找到运行时(`build`) |
| `create-release` | — | GitHub release、覆盖全部归档的 `SHA256SUMS` | 四个构建或 `promote`(及运行时的 canaries) |
| `release-manifest` | — | `mcpp-release.json` | `create-release` |
| `publish-ecosystem` | — | 镜像到 xlings-res 双端 + 开索引 bump PR | `release-manifest` |

Expand Down
2 changes: 2 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,5 @@
tests/fixtures/openkal-hosted-threads/src/main.cpp.in text eol=lf
# The rows' snapshot is compared line by line with what the engine answers, in its own bytes.
tests/fixtures/target-rows.snapshot text eol=lf
# The golden outputs are compared whole with what mcpp writes, in its own bytes (tests/e2e/cli/golden.cpp).
tests/e2e/golden/* text eol=lf
2 changes: 1 addition & 1 deletion .github/actions/bootstrap-mcpp/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ inputs:
# `package.name`, so one of the two was simply unreachable — and which one
# depended on the machine, which is why CI failed on `compat:lua` on
# Windows and `mcpplibs.capi:lua` on Linux. Never pin below that.
default: '2026.11.17.2'
default: '2026.11.21.1'

outputs:
sandbox-key:
Expand Down
Loading
Loading