From b7cc13ad5ac888c1fd6466b94c60e087c71ba7b6 Mon Sep 17 00:00:00 2001
From: speak-agent <248744407+speak-agent@users.noreply.github.com>
Date: Mon, 17 Aug 2026 08:07:09 +0800
Subject: [PATCH] docs: cxx_runtime was inert on MSVC until 2026.8.16, and
 upgrading is silent
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The MSVC section describes today's behaviour correctly and says nothing about
the fact that it is NEW. Through 2026.8.15 the key reported "not implemented
for the MSVC runtime yet" and every value fell back to /MD; since 2026.8.16
(#422) it selects the CRT model.

So a manifest carrying `cxx_runtime = "self-contained"` from that era switches
from /MD to /MT on upgrade — silently, because the value was always spelled
correctly and always accepted. /MT is a different CRT model rather than a
stricter version of the same one.

Not hypothetical: found while reviewing xrgui's mcpp manifest, which carried
exactly that value, set at a time when it did nothing, with a comment
explaining that it was a no-op.
---
 docs/05-mcpp-toml.md    | 8 ++++++++
 docs/zh/05-mcpp-toml.md | 7 +++++++
 2 files changed, 15 insertions(+)

diff --git a/docs/05-mcpp-toml.md b/docs/05-mcpp-toml.md
index 1d1b6a82..a5e663eb 100644
--- a/docs/05-mcpp-toml.md
+++ b/docs/05-mcpp-toml.md
@@ -423,6 +423,14 @@ machine that has only the pinned toolset and no Visual Studio at all.
 The debug CRT (`vcruntime140d.dll` and friends, under `debug_nonredist\`) is
 never staged: it may not be redistributed.
 
+> **Upgrading from 2026.8.15 or earlier?** This key used to be **inert** on the
+> MSVC ABI — it reported `not implemented for the MSVC runtime yet` and every
+> value fell back to `/MD`. Since 2026.8.16 it is honoured, so a manifest that
+> carries `cxx_runtime = "self-contained"` from that era **changes CRT model on
+> upgrade**, from `/MD` to `/MT`. It is not a stricter version of the same
+> model, and the switch is silent because the value was always valid. If your
+> project set it while the key did nothing, decide which one you actually want.
+
 Combining it with `/MT` is a contradiction rather than a missing feature — a
 static CRT leaves no DLL to couple to — so it is reported and resolved to
 `self-contained`. `mcpp pack` enforces the other half: a mode that bundles
diff --git a/docs/zh/05-mcpp-toml.md b/docs/zh/05-mcpp-toml.md
index b6af2965..b5263377 100644
--- a/docs/zh/05-mcpp-toml.md
+++ b/docs/zh/05-mcpp-toml.md
@@ -375,6 +375,13 @@ Windows 组件(Win10 起),mcpp 从不分发它;而 `vcruntime140.dll` /
 调试版 CRT(`debug_nonredist\` 下的 `vcruntime140d.dll` 等)永远不会被放进去:
 它不可再分发。
 
+> **从 2026.8.15 或更早版本升上来?** 这条键在 MSVC ABI 上曾经是**空操作** ——
+> 它会报 `not implemented for the MSVC runtime yet`,写什么都退回 `/MD`。
+> 自 2026.8.16 起它真的生效,于是一份从那个年代带着
+> `cxx_runtime = "self-contained"` 的 manifest **会在升级时换掉 CRT 模型**:
+> 从 `/MD` 变成 `/MT`。它不是同一个模型的更严格版本,而且因为这个值一直是合法的,
+> 切换是**静默**的。如果你的工程是在这条键还不起作用时写下它的,请重新决定你真正要哪一个。
+
 把它和 `/MT` 一起用是**矛盾**而不是缺功能 —— 静态 CRT 根本没有 DLL 可以耦合 ——
 所以会被报出来并落到 `self-contained`。另一半由 `mcpp pack` 兜底:什么都不打包的
 模式(`--mode system`、`--mode static`)兑现不了 `toolchain-coupled`,会直接拒绝。