Rust 语言特性稳定化报告Stabilization Report模板全解析从 TODO 到可审阅的稳定化提案【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust本文以 rustc 编译器仓库 rustc-dev-guide 中的《Stabilization report template》为骨架系统讲解一份面向 lang 团队的稳定化报告应当如何撰写每个章节要回答什么问题、评审者关注哪些细节、如何组织代码示例与测试证据并结合仓库内的稳定化流程指南、feature gate 生命周期源码compiler/rustc_feature/src/unstable.rs、compiler/rustc_feature/src/accepted.rs给出可落地的实操指引。读完本文你将掌握从特性在 nightly 上成熟到撰写报告、提名 lang 团队、进入 FCP 合并全链路中报告撰写的核心方法论。什么是稳定化报告为什么它是稳定化的关键一环Rust 语言特性language feature从 RFC 通过、进入 nightly 实现到最终在 stable 上向所有用户开放中间必须经过稳定化stabilization这一步。在这个环节需要有人撰写一份稳定化报告stabilization report把该特性从设计到实现、从决策到争议、从测试到工具链配合的全部关键信息结构化地呈现给 lang 团队评审。官方模板位于 src/doc/rustc-dev-guide/src/stabilization-report-template.md它是 rustc-dev-guide 中《Stabilizing language features》一章的直接配套产物——该流程指南明确要求使用本仓库中的模板撰写稳定化报告见 稳定化流程指南并且报告通常以稳定化 PR 主评论的形式发布。模板的作用可从两个角度看对撰写者模板的问题清单是最容易遗漏的细节清单引导你把设计决策、偏离 RFC 之处、与类型系统/操作语义opsem子团队的交互、测试覆盖、工具链配合等全部想清楚对评审者模板把 lang 团队评审时最常追问的问题前置帮助评审者提前发现潜在问题而不是在合并前才暴露。模板只针对语言特性的稳定化标准库 API 的稳定化走另一套机制见 stability.md。模板的使用方法模板开头明确给出了使用说明复制分隔线---之后的全部内容以 Markdown 形式编辑将每个*TODO*替换为你的答案如果某个问题不适用于本次稳定化简要说明不适用的原因而不是直接删除或留空。模板中的 引用块部分是给撰写者的引导问题告诉你要回答什么、为什么重要最终提交的报告应把这些问题消化为正式的正文内容。下述所有小节的标题均与模板一一对应。Summary讲清楚这是什么、为什么值得稳定报告的## Summary是整个文档的电梯演讲。模板要求提醒评审者这个特性是什么、它提供了什么价值并讲述导致这次稳定化的来龙去脉Tell the story of what led up to this stabilization。模板列出的优秀范例均为历史上真实的大型稳定化报告包括AFIT/RPITITasync fn in trait / return-position impl trait in trait的稳定化RTNreturn type notation返回类型记法的稳定化ATPITassociated type position impl trait的稳定化opaque type precise capturing不透明类型精确捕获的稳定化。这些案例的共同点是特性都经历了漫长的设计讨论报告需要把为什么现在稳定的故事讲清楚。从 walkthroughs/lang-feature.md 中的?Kleene 宏操作符案例可以看到这类特性的完整生命周期Pre-RFC 讨论 → RFC → nightly 实现 → 多轮迭代打磨 → 稳定化 → 转正。稳定化报告正是这个生命周期收尾时最重要的产出物。Summary 小节还要求列出两类链接Tracking指向该特性的跟踪 issuetracking issueReference PRs指向语言参考手册The Reference中描述该特性的 PR。同时按惯例cc rust-lang/lang rust-lang/lang-advisors把 lang 团队及其顾问拉入评审。What is stabilized给出现在会被接受的代码模板要求逐一描述被稳定的行为并给出简短示例展示此前无法编译、现在可以编译的代码。示例用 Rust 代码块给出模板中以todo!()占位todo!()一个合格示例应该突出新语法/新行为本身让评审者一眼看出稳定化的边界。例如pub(restricted)稳定化时示例就应当展示pub(crate)、pub(in path)等可见性语法。What isnt stabilized明确哪些部分还没稳定模板要求描述没有被稳定化的部分包括未来可能做的事以及为这些预留了哪些门doors如果未稳定部分可能给用户带来意外例如用了半套语法要特别说明。这个稳定什么、不稳定什么的边界描述是整个报告最容易被评审者追问的部分。Design设计决策的完整账本## Design是报告的主体模板细分了七个问题覆盖设计层面评审者关心的一切。Reference参考手册需要哪些更新模板要求逐一链接每个 Reference PR并讨论手册中是否缺少描述该特性所需的内容。这一点在稳定化流程指南中有硬性要求The Reference必须被完整更新且必须由 lang-docs 团队成员审阅批准后稳定化才能合并。RFC history列出为该特性接受的所有 RFC。一个特性可能涉及多份 RFC主 RFC 后续修正 RFC都需要登记。Answers to unresolved questionsRFC 中往往有Unresolved Questions未决问题一节。模板要求这些问题后来是如何回答的并链接相关的 lang 决策记录。这正是稳定化报告的核心价值之一——RFC 通过时没想清楚的事经过 nightly 实践后有了答案要把这些答案正式记录在案。Post-RFC changes模板要求描述 RFC 接受之后发生的其他用户可见变更并且要区分两类lang 团队已经批准并链接到相应决策的变更首次在本次稳定化报告中呈现给团队的变更。流程指南特别强调最终稳定下来的语言特性往往与最初的 RFC 有显著设计偏差。这没关系但这些偏差必须被突出强调并仔细解释见 稳定化流程指南。Key points哪些决策最难哪些行为最富争议模板要求总结各方的核心论点并链接到先前的文档和讨论。写这一节时切忌只写结论要把当时为什么选 A 不选 B的论证过程保留下来这对未来的评审者极有价值。Nightly extensions是否存在仍未稳定的扩展模板特别追问我们如何知道不会意外承诺这些扩展也就是说要论证稳定化的边界是精确的用户无法通过稳定部分偷渡使用不稳定扩展。Doors closed这次稳定化关闭了哪些门即它是否让其他 RFC、lang 实验或在途提案在将来变得更难甚至不可能实现这一节与 What isnt stabilized 呼应但视角是对语言未来的影响而不是对当前用户的边界。Feedback来自社区的实践证据Call for testing是否进行过征集测试call for testing收到了什么反馈这是特性上线 nightly 后主动向社区征集的试用意见稳定化前应已有结论。Nightly use已知有哪些 nightly 用户在使用该特性模板给出一个实用技巧在 GitHub 上用 grep 统计#![feature(FEATURE_NAME)]的出现次数可能很有信息量。这一数据能直观反映特性的实际采用面帮助团队判断稳定化的社会成本/收益。Implementation实现层面的完整交代Major parts总结实现的主要组成部分并给出代码与相关 PR 的链接。模板以 async closures 为例指出可以按功能模块拆分实现如协程闭包的各个编译阶段。对于本仓库实现通常分布在 compiler 下的各 rustc crate 中例如 AST 解析与校验在 compiler/rustc_ast_passes、类型检查在 compiler/rustc_hir_typeck 与 compiler/rustc_trait_selection、MIR 层面在 compiler/rustc_mir_build 等撰写时应把关键实现文件精确链接出来。Coverage模板对测试覆盖提出了非常具体的要求总结该特性的测试覆盖情况思考特性的边缘是什么特别关注那些能证明附近哪些东西我们确实没有稳定的测试测试当然要全面证明特性工作正常还要展示常见误用场景下的诊断信息diagnostics测试每个测试文件顶部都要加注释说明该测试的目的以及它试图证明的不变量集合——这能极大帮助评审说明已知或有意的测试覆盖缺口链接测试文件夹与具体测试。在本仓库中语言特性测试集中在 tests/uiUI 测试含.stderr诊断基线、tests/mir-optMIR 优化与转换测试、tests/assembly-llvm 与 tests/codegen-llvmLLVM 代码生成级测试、tests/incremental增量编译测试等目录撰写报告时应将测试证据分布到这些目录中。Outstanding bugs列出涉及该特性的未解决问题并逐一说明是否应阻塞本次稳定化为什么不。模板给出了三个*TODO*占位实际可按问题数量增减。Outstanding FIXMEs代码中还有哪些针对该特性的FIXME以及为什么留下它们是可以接受的。评审者需要确认遗留 FIXME 不是隐藏的未完成工作。Tool changes模板给出了一份工具链配合清单逐项确认其他工具是否需要改动以及是否已完成rustfmtrust-analyzerrustdocJSON 与 HTML 两种输出cargoclippyrustupdocs.rs在本仓库中这些工具的源码大多位于 src/tools如 src/tools/rustfmt、src/tools/clippy、src/tools/rust-analyzerrustdoc 本体在 src/librustdoc。每项都要链接相关 PR 与 issue若某工具无需改动也应说明。Breaking changes如果本次稳定化是已知的破坏性变更模板要求链接crater report用 crater 工具对 crates.io 生态做的大规模编译测试报告链接对 crater 报告的分析链接所有为受影响的生态项目做出的修复 PR讨论我们能知道什么、能修复什么的局限。模板为此预留了 Crater report:、Crater analysis:、PRs to affected crates: 三个列表。Type system, opsem类型系统与操作语义的交叉审查这一大节专门服务 lang 团队的 types 与 opsem 子团队是模板中最编译器内部的部分。Compile-time checks为了阻止未定义行为UB编译期做了哪些检查每项检查都要链接到证明其生效的测试。Type system rules该特性强制执行了哪些类型系统规则每条规则的目的分别是什么例如借用规则、生命周期约束、auto trait 传播等逐条列出并说明动机。Sound by default?该特性的实现是否需要专门的检查来防止 UB还是默认就是 sound安全的需要显式 opt-in 才执行危险/不安全操作如果它不是默认 sound 的理由是什么——Rust 的语言特性默认应当 sound任何例外都必须给出充分论证。Breaks the AM?用户能否用该特性引入未定义行为或破坏 Rust 的抽象、暴露底层的汇编级实现例如通过transmute、asm!、#[repr(C)]等逃逸路径。模板要求如实描述这类可能性。Common interactions与既有语言机制的相互作用这一节检查新特性与 Rust 既有语义的交互问题都非常具体。Temporaries该特性是否引入了会产生临时值temporaries的新表达式这些临时值的生命周期作用域是什么临时值作用域直接关系到借用检查与 drop 时机。Drop order该特性是否引发值析构顺序的疑问模板要求说明此处的决策及其与既有决策的一致性。Pre-expansion / post-expansion该特性是否引发宏展开前pre-expansion例如#[cfg(false)]覆盖的代码该接受什么、展开后post-expansion该接受什么的问题以及做出了什么决策。Edition hygiene如果特性按 edition 门控在 token 的 edition hygiene 语境下如何决定接受还是拒绝代码例如用哪个 token 来判定这关系到多 edition 混编时宏展开 token 的来源版本。SemVer implications该特性是否创造了库作者在 minor 版本发布时需要注意的新风险模板要求按 RFC 1105API 演进 的标准判断这些新风险属于major还是minor。注意RFC 1105 定义的是库 API 演进契约如向 trait 添加默认方法属 minor 破坏语言新语法会间接影响库作者对下游兼容性的判断。Exposing other features是否有其他不稳定特性的行为会被该特性以某种方式暴露哪些特性存在最高风险例如新语法可能意外触发某个不稳定特性的代码路径。History、Acknowledgments、Open items收尾三件套History列出对理解我们如何走到今天至关重要的 issue 与 PR。Acknowledgments按姓名致谢该特性的主要贡献者既表达认可也让这些人能被通知到稳定化一事模板还特别要求说明是否有参与工作的人认为现在还不应稳定化如果有希望听到理由。Open items列出在稳定化之前仍需完成的已知事项以 checkbox 清单形式模板给出三个- [ ]占位。配套流程稳定化报告之外仓库里还有哪些硬性步骤稳定化报告只是流程一环。结合 稳定化流程指南 与 Feature Gates 章节报告中涉及的若干断言在仓库里有对应的具体文件操作撰写报告时应当对这些步骤心里有数更新 feature-gate 清单unstable.rs → accepted.rs特性稳定时需要在 compiler/rustc_feature/src/unstable.rs 的declare_features!宏位于该文件第 208 行附近中找到该特性的声明形如// pub(restricted) visibilities (RFC 1422) (unstable, pub_restricted, CURRENT_RUSTC_VERSION, Some(32409)),示例取自稳定化流程指南CURRENT_RUSTC_VERSION为占位符稳定化时不要写预期版本号应保留该字面量。然后将该行移动到 compiler/rustc_feature/src/accepted.rs 的declare_features!宏第 23 行起中把unstable改为accepted并按字母序归位// pub(restricted) visibilities (RFC 1422) (accepted, pub_restricted, CURRENT_RUSTC_VERSION, Some(32409)),在 accepted.rs 中可以看到该文件自带的注释约束Features are listed in alphabetical order. Tidy will fail if you dont keep it this way.按字母序排列tidy 检查会失败以及 the version indicates when it gotstabilized。相应地unstable.rs 中(internal, ...)/(unstable, ...)声明则保留给仍不稳定的特性。移除 gate 检查feature_gate.rs稳定化的核心动作是去掉必须开 feature gate 才能用的限制。对于依赖新语法的特性gate 检查代码通常位于 compiler/rustc_ast_passes/src/feature_gate.rs例如gate_all!(pub_restricted, pub(restricted) syntax is experimental);gate_all!宏在未开启pub_restricted时报告错误特性稳定后这行应删除。对于更细粒度的特性代码中常形如if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ }稳定化后应把if条件直接删除、保留/* XXX */本体详细转换示例见稳定化流程指南。团队提名与 FCP报告与稳定化 PR 就绪后PR 中cclang 团队及相关子团队types、opsem、compiler、libs、lang-docs 等等评论平息后将 PR提名nominate到 lang 会议议程团队审阅通过后由团队成员发起rfcbot fcp merge进入最终评论期FCP无人提出新问题则 FCP 完成PR 在常规实现评审后合并。评审者放行r前要确认 PR 与团队批准内容、Reference PR、稳定化报告及 RFC/FCP 决策完全一致且不把稳定范围之外的行为暴露到 stable见稳定化流程指南。撰写实践建议把模板变成高质量报告综合模板与仓库内的配套文档撰写时值得坚持以下几点逐节填写不适用就说明理由每个*TODO*都要有结果确不适用时写一句不适用因为……这是模板明确要求的。示例代码要最小且聚焦What is stabilized 的示例应是评审者能一眼看出语法边界的最小程序。测试证据指向具体路径在本仓库中把 UI 测试、诊断测试、mir-opt 测试、代码生成测试分别链接到 tests/ui、tests/mir-opt、tests/codegen-llvm、tests/assembly-llvm 等目录下的具体文件并遵守测试文件顶部写注释说明意图的约定。讲清偏差与争议偏离 RFC 的设计决策是评审重点务必显式列出并链接决策依据What isnt stabilized与Doors closed两节共同划清边界。把声音soundness论证写扎实Compile-time checks、Type system rules、Sound by default 三节是 opsem/types 子团队评审的重心UB 防护路径必须配测试链接。检查清单逐项落实Tool changes 的七项工具清单与 Open items 的 checkbox 要在合并前清零或有明确结论。结语稳定化报告模板的价值不在于填表格而在于它强制把 lang 团队评审所需的全部上下文——设计故事、边界、决策、测试、soundness、工具链配合——一次性结构化呈现。它既保护了撰写者免于遗漏也保护了评审者免于在合并前夕才发现重大问题。当你在 nightly 上打磨出一个语言特性并准备让它走向 stable 时这份模板就是你的完整作战地图填好每一个*TODO*把边界与声音论证讲透再配合 feature gate 清单的迁移unstable.rs → accepted.rs与 feature_gate.rs 的 gate 移除你的特性就具备了进入 lang 团队议程、走完 FCP 并最终合并的全部条件。【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考