QA: Snippets' Test

[arrowrowe]

主题: 代码片段的质量保证. 相关: #375, #385, #399, ......

• 现存问题
  • 书中代码片段没有自动化的质量保证.
• 可供参考的方案
  • Rust by Example 的方案:
    • 代码单独放, 正文中引用其位置, 而非代码本身. 参考它的 README.md, 特别是 Processing input.md 中对 {hello.play}, {hello.rs} 和 {hello.out} 的说明.
    • 预处理时使用 rustc -Z no-trans --test 检查所有代码. 参考它的 Makefile, 特别是第 5 行和第 46 行.
  • 这个分支 中的方案:
    • 增加测试. 具体过程为, 提取正文中代码并输出, 然后编译并运行.
    • 优点: 正文所需改动稍小 (有 12 章不需要改动). 是在已有的测试流程上增加的, 不用改变整个流程.
• 上述方案的问题
  • 共同的问题是正文修改工作量较大. 要保证每个代码片段都单独可运行, 这对作者的书写习惯有要求. (不过, 两个方案都允许豁免某些代码片段.)
  • Rust by Example 方案需要引入插件并配置, 改变整个发布流程. (不确定工作量如何.)
  • 某些章节 (如 Any 和反射) 需要 nightly, 要特殊考虑. (也可以直接豁免掉这些特例, 人工检查.)

以上. 请多指教......

[Librazy]

辛苦了。 我的建议是两种相结合，对于较为大段的例子（有关本章节的一个完整的示例程序）采用第一种方案，对于代码片段（主要用于介绍某一特定对象）采用第二种方案。 其中：

• 完整示例：一个完整的crate，存放在指定目录，要求可通过cargo run执行。代码采用引用的方式链接进MD文档，对于代码的介绍以注释形式存在于.rs文件内。对于有特殊编译版本要求的程序，可以使用 rustup override add <toolchain> 的方式指定编译版本。
• 代码片段：有且仅有一个main函数，要求复制粘贴即可执行。对于网页版也可做成一个Rust Playground的控件。原则上应尽可能精简。暂未想到如何处理编译器版本依赖问题。

[arrowrowe]

稍微补充一下. 第二种方案提取时, 会把不含 main 函数的片段用 'fn main() {\n', '\n}' 包起来, 参见 test/snippet.spec.js#L11.

两种相结合 +1

[wayslog]

编译发布组的工作量无所谓……反正就我自己~~ 回头我研究研究这东西怎么玩