Skip to content

fix(doc): Fix docs.rs build failure for metrique crate#245

Merged
jlizen merged 2 commits into
awslabs:mainfrom
jlizen:fix/docsrs-build
Mar 17, 2026
Merged

fix(doc): Fix docs.rs build failure for metrique crate#245
jlizen merged 2 commits into
awslabs:mainfrom
jlizen:fix/docsrs-build

Conversation

@jlizen
Copy link
Copy Markdown
Contributor

@jlizen jlizen commented Mar 17, 2026

Fix docs.rs build failure for metrique crate

Summary

The docs.rs build for metrique 0.1.21 fails because the global-state example has doc-scrape-examples = true and uses metrique_util::State, but metrique-util was only a dev-dependency. On docs.rs, dev-dependencies are stripped, so example scraping fails with unresolved import metrique_util.

Two changes:

  1. check-docsrs.sh: the script was not catching this class of failure. When the packaged docs-rs build failed, it silently fell back to a workspace build where dev-deps are available, masking the error. The fix removes the fallback when the packaged build itself fails (the fallback is preserved only when cargo package fails, e.g. for unpublished crates). It also restores doc-scrape-examples = true flags that cargo package may strip from the packaged Cargo.toml, so the packaged build faithfully reproduces docs.rs behavior.

  2. metrique/Cargo.toml: adds metrique-util as an optional dependency behind a new util feature (which enables metrique-util/state). The global-state example is gated on required-features = ["emf", "service-metrics", "util"]. Since docs.rs builds with --all-features, the feature is enabled and the example compiles during doc scraping.

Testing

  • Verified check-docsrs.sh metrique reproduces the exact docs.rs error before the Cargo.toml fix (E0432: unresolved import metrique_util).
  • Verified check-docsrs.sh metrique passes after the Cargo.toml fix.
  • cargo check -p metrique --all-features passes.

🔏 By submitting this pull request

  • I confirm that I've made a best effort attempt to update all relevant documentation.
  • I confirm that my contribution is made under the terms of the Apache 2.0 license.

The packaged docs-rs build was falling back to a workspace build on
failure, masking errors where scraped examples reference dev-only
crates. Remove the fallback when the packaged build fails (only fall
back when cargo package itself fails). Also restore doc-scrape-examples
flags that cargo package may strip, so the packaged build faithfully
reproduces docs.rs behavior.
@jlizen jlizen requested a review from rcoh March 17, 2026 22:46
@jlizen jlizen marked this pull request as draft March 17, 2026 22:47
The example uses metrique_util::State (a dev-dep), which is unavailable
during doc scraping on docs.rs. Set doc-scrape-examples = false.
@jlizen jlizen force-pushed the fix/docsrs-build branch from 5bfac62 to 38ee993 Compare March 17, 2026 22:52
@jlizen jlizen marked this pull request as ready for review March 17, 2026 23:05
@jlizen jlizen merged commit b25f55e into awslabs:main Mar 17, 2026
10 checks passed
@jlizen jlizen deleted the fix/docsrs-build branch March 17, 2026 23:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants