Doctests are compiled in one feature configuration, and a defect in any other is invisible
- 主要語言
- 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 還沒有評估資料。