akiomik / akiomik/tears

Doctests are compiled in one feature configuration, and a defect in any other is invisible

未關閉
#400 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視
documentation
主要語言
Rust
星號
9
分支
1
平均合併
11 小時 46 分鐘
30 天內合併 PR
62

描述

## What

Every doctest this repository runs is run under one feature set. `just test-doc`
is `cargo test --doc --features {{user_features}}`, `just test-doc-packaged`
runs the same list against the packaged crate, and those two are the whole of
it — `pre-commit` and `check` list `test-doc` and nothing else, and `ci.yml`'s
`doctest` job runs those two recipes. No local recipe and no CI step runs
`cargo test --doc` under any other set.

So a doc example is compiled in exactly one configuration, and a defect that
only shows in another is invisible until someone runs that configuration by
hand.

## The instance

#398 hit one. `subscription::http` was declared
`#[cfg(any(feature = "http", feature = "loom-core"))]` while everything inside
it is `#[cfg(feature = "http")]`, so `cargo test --doc --features loom-core`
reached the module's example with none of the re-exports it names:

```
error[E0432]: unresolved import `tears::subscription::http::QueryError`
note: found an item that was configured out
```

It failed on `main` and had failed since that example stopped being `ignore`.
Nothing reported it, because nothing runs that command. It was found while
re-measuring a number in a comment.

## The class, and why a guard is not obvious

The class is wider than the instance: a doc example compiled under a feature
set that does not enable everything it names. `user_features` enables `http`
and `ws` together, so it hides every example that needs one and sits behind the
other, and it hides every example in a module reachable under a third feature.

What a guard would have to run is the open question:

- **`cargo test --doc` with no features.** Cheap, and catches an example outside
a gate that names gated API — the class `CONTRIBUTING.md` now has a
convention for. It would *not* have caught the instance above: with neither
`http` nor `loom-core` the module is not compiled at all.
- **`cargo test --doc --features loom-core`.** Catches the instance. Guards a
configuration that exists only because one test-only feature reaches into one
module, which #398 has since narrowed.
- **A set per feature.** Catches the class and costs a doctest compilation per
feature; the crate has eight a dependant can name.

Each is a different answer to what a local run guarantees, which is #395's
question rather than something this observation settles.

Raised in review of #398.

貢獻指南

開啟貢獻指南

評估

這個 Issue 還沒有評估資料。

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。