Reducing build times on documentation pull requests


#1

As I’m sure we’re all aware, building and testing Rust on travis takes a long time. This is a particular pain for documentation or comment PRs where there is no actual code change so we’re spending a long building something we know will work. As an example #54085 a PR that removes 7 lines of documentation took over an hour and a half of build time.

I have built a tool called Hera using Tokei’s language detection and regular expressions detects if there has been any code changes between commits. This will even detect code that is in a code fence and treats that as code so someone updating or adding example code would still be tested but PRs like the one mentioned above would be completely skipped.

I’ve written quite a few tests and a bit of functionality such as filtering which languages count as code, but I want to get some feedback on this before doing anything more.


#2

Two random notes about this:

  • We actually test something for docs-only PRs, like if all the links points to something – an approach we could take instead is to skip building unneeded things, but still build and check the docs
  • While reducing build times on commit builds in the PRs would be great, I don’t think we can do this for bors merge commits, mostly because those also upload artifacts (and also docs PRs always go into a rollup, so there isn’t a lot of wasted time there)

#3

Currently, if you just want to view docs, you also need to have built a compiler. This causes a lot of wasted time for docs contributors, and “why do i have to build LLVM to make docs” questions. If there was a way to make stage0 docs work (including rustdoc in the bootstrap? supporting stage0 builds of rustdoc and linkchecker from the bootstrap rustc?) that would already be a massive boon, though from your comment i think you’re proposing skipping builds entirely?

Logistically speaking, where would this check fit? The CI scripts? Bootstrap? That dictates how the integration effort would be spent.


#4

FWIW, rustdoc is already included in the rustc-* tarball that’s used for bootstrap, and it’s extracted to stage0/bin/ with everything else.


#5

Well initially I was thinking that it would go into the CI scripts, right now it wouldn’t work in bootstrap as it diffs between the HEAD^ and the HEAD, but I could definitely add the option to check between the diff of the HEAD to the current working directory. Also this is currently a binary, but there’s no requirement on how it works being a binary, the function could just as easily be in a library and called from a build script or something similar.


#6

Note that you’ll also need to exclude any cases where a procedural macro attribute gets wrapped around the doc comment (which turns into an attribute itself and may get parsed and acted on).


#7

Is there actual cases of that in the rust repository? I know that is possible (It’s already possible with normal macros.), but I don’t know of a way to handle magic comments.


#8

Related issue: