Skip to content

ci: run doctests in ci and make test-rust - #1014

Open
dragonknightk wants to merge 1 commit into
apache:mainfrom
dragonknightk:ci/run-doctests
Open

dragonknightk wants to merge 1 commit into
apache:mainfrom
dragonknightk:ci/run-doctests

Conversation

@dragonknightk

Copy link
Copy Markdown

Description

CI and make test-rust only run cargo test --all-targets, which skips doctests, so the examples in rustdoc comments (including the crate docs docs.rs renders for hudi and hudi-datafusion) could break after an API change without any check failing. This adds a make test-rust-doc target that runs them, calls it from make test-rust, and runs it as a step in the rust-tests CI job.

Closes #970

  • The step sits in the existing tarpaulin job because tarpaulin runs lib, bin and integration test targets only, and doctest coverage there would need a nightly toolchain. It costs one extra compile, since tarpaulin's instrumented artifacts cannot be reused for doctests; keeping it in this job avoids another runner setup and keeps all Rust test results in one place.
  • hudi-cpp is excluded. Its lib target is named hudi, the same as its hudi dependency, so rustdoc receives two --extern hudi candidates and fails with E0464 before running anything. The crate has no rustdoc examples. Setting doctest = false on it does not help, because an explicit --doc overrides that flag.
  • Every example outside ignore blocks already compiled and passed. ignore blocks are not compiled at all, so this change also converts the 8 ignore examples in hudi-core. Seven become no_run, with hidden lines for the async main, imports and placeholder paths, and their compile errors are fixed against the current API: two imported from hudi, which is not a dependency of hudi-core, FileGroupReader::read_file_slice_stream passed the Result from with_batch_size without ?, and HFileReader::open iterated a reader not bound as mut. The eighth, on HoodieMergedLogRecordReader, documents a type that is not reachable outside the crate (its module is pub(crate)), so a doctest cannot use it, and it becomes a text block. No ignore doctests remain.
  • AGENTS.md lists the new target. crates/AGENTS.md asks that a new example needing a real table be written as no_run with hidden setup lines, and that a sketch on an item not reachable outside the crate use a text block.

How are the changes test-covered

  • N/A
  • Automated tests (unit and/or integration tests)
  • Manual tests
    • Details are described below

The new CI step is itself the coverage: from now on every rustdoc example is compiled, and run unless marked no_run, on each pull request.

Manual run of make test-rust-doc on Rust 1.94.1:

  • hudi: 6 pass
  • hudi-core: 16 pass (9 run, 7 compile-only no_run), 0 ignored
  • hudi-datafusion: 2 pass (compile-only, no_run)
  • Without --exclude hudi-cpp, the same command fails on hudi-cpp with E0464.

AI Disclosure

Human-led contribution. Grok Bot, working for dragonknightk, assisted with this change. All submitted content was reviewed by a human before submission.

(๑•̀ㅂ•́)و✧

## Description

CI and `make test-rust` only run `cargo test --all-targets`, which skips doctests, so the
examples in rustdoc comments (including the crate docs docs.rs renders for `hudi` and
`hudi-datafusion`) could break after an API change without any check failing. This adds a
`make test-rust-doc` target that runs them, calls it from `make test-rust`, and runs it as a
step in the `rust-tests` CI job.

Closes issue 970

- The step sits in the existing tarpaulin job because tarpaulin runs lib, bin and integration
  test targets only, and doctest coverage there would need a nightly toolchain. It costs one
  extra compile, since tarpaulin's instrumented artifacts cannot be reused for doctests; keeping
  it in this job avoids another runner setup and keeps all Rust test results in one place.
- `hudi-cpp` is excluded. Its lib target is named `hudi`, the same as its `hudi` dependency, so
  rustdoc receives two `--extern hudi` candidates and fails with E0464 before running anything.
  The crate has no rustdoc examples. Setting `doctest = false` on it does not help, because an
  explicit `--doc` overrides that flag.
- Every example outside `ignore` blocks already compiled and passed. `ignore` blocks are not
  compiled at all, so this change also converts the 8 `ignore` examples in hudi-core. Seven
  become `no_run`, with hidden lines for the async main, imports and placeholder paths, and their
  compile errors are fixed against the current API: two imported from `hudi`, which is not a
  dependency of hudi-core, `FileGroupReader::read_file_slice_stream` passed the `Result` from
  `with_batch_size` without `?`, and `HFileReader::open` iterated a reader not bound as `mut`.
  The eighth, on `HoodieMergedLogRecordReader`, documents a type that is not reachable outside
  the crate (its module is `pub(crate)`), so a doctest cannot use it, and it becomes a `text`
  block. No `ignore` doctests remain.
- AGENTS.md lists the new target. crates/AGENTS.md asks that a new example needing a real table
  be written as `no_run` with hidden setup lines, and that a sketch on an item not reachable
  outside the crate use a `text` block.

## How are the changes test-covered

- [ ] N/A
- [x] Automated tests (unit and/or integration tests)
- [x] Manual tests
  - [x] Details are described below

The new CI step is itself the coverage: from now on every rustdoc example is compiled, and run
unless marked `no_run`, on each pull request.

Manual run of `make test-rust-doc` on Rust 1.94.1:
- `hudi`: 6 pass
- `hudi-core`: 16 pass (9 run, 7 compile-only `no_run`), 0 ignored
- `hudi-datafusion`: 2 pass (compile-only, `no_run`)
- Without `--exclude hudi-cpp`, the same command fails on `hudi-cpp` with E0464.

## AI Disclosure

Human-led contribution. Grok Bot, working for dragonknightk, assisted with this change. All
submitted content was reviewed by a human before submission.

Signed-off-by: dragonknightk <37928252+dragonknightk@users.noreply.github.com>
@dragonknightk

Copy link
Copy Markdown
Author

@yihua Thanks for raising this! This is my first PR in hudi-rs, so the workflows are waiting for approval to run. Could you approve them when you have a moment? (´。• ᵕ •。`)

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.

Run doctests in CI

1 participant