Skip to content

Commit ae6a6d4

Browse files
committed
CI tool usage (#3876)
# Objective - Original objective was to add doc build warning check to the ci local execution - I somewhat deviated and changed other things... ## Solution `cargo run -p ci` can now take more parameters: * `format` - cargo fmt * `clippy` - clippy * `compile-fail` - bevy_ecs_compile_fail_tests tests * `test` - tests but not doc tests and do not build examples * `doc-test` - doc tests * `doc-check` - doc build and warnings * `bench-check` - check that benches build * `example-check` - check that examples build * `lints` - group - run lints and format and clippy * `doc` - group - run doc-test and doc-check * `compile` - group - run compile-fail and bench-check and example-check * not providing a parameter will run everything Ci is using those when possible: * `build` jobs now don't run doc tests and don't build examples. it makes this job faster, but doc tests and examples are not built for each architecture target * `ci` job doesn't run the `compile-fail` part but only format and clippy, taking less time * `check-benches` becomes `check-compiles` and runs the `compile` tasks. It takes longer. I also fixed how it was using cache * `check-doc` job is now independent and also run the doc tests, so it takes longer. I commented out the deadlinks check as it takes 2.5 minutes (to install) and doesn't work
1 parent 2c14582 commit ae6a6d4

File tree

4 files changed

+113
-38
lines changed

4 files changed

+113
-38
lines changed

.github/workflows/ci.yml

Lines changed: 30 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,8 @@ jobs:
4141
run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev
4242
if: runner.os == 'linux'
4343
- name: Build & run tests
44-
run: cargo test --workspace
44+
# See tools/ci/src/main.rs for the commands this runs
45+
run: cargo run -p ci -- test
4546
env:
4647
CARGO_INCREMENTAL: 0
4748
RUSTFLAGS: "-C debuginfo=0 -D warnings"
@@ -68,7 +69,7 @@ jobs:
6869
run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev libwayland-dev libxkbcommon-dev
6970
- name: CI job
7071
# See tools/ci/src/main.rs for the commands this runs
71-
run: cargo run -p ci -- nonlocal
72+
run: cargo run -p ci -- lints
7273

7374
miri:
7475
runs-on: ubuntu-latest
@@ -102,7 +103,7 @@ jobs:
102103
# to raw pointer aliasing rules that we should be trying to uphold.
103104
MIRIFLAGS: -Zmiri-disable-isolation -Zmiri-ignore-leaks -Zmiri-tag-raw-pointers
104105

105-
check-benches:
106+
check-compiles:
106107
runs-on: ubuntu-latest
107108
needs: ci
108109
steps:
@@ -115,15 +116,17 @@ jobs:
115116
~/.cargo/registry/cache/
116117
~/.cargo/git/db/
117118
target/
118-
key: ${{ runner.os }}-cargo-check-benches-${{ hashFiles('**/Cargo.toml') }}
119+
crates/bevy_ecs_compile_fail_tests/target/
120+
key: ${{ runner.os }}-cargo-check-compiles-${{ hashFiles('**/Cargo.toml') }}
119121
- uses: actions-rs/toolchain@v1
120122
with:
121123
toolchain: stable
122124
override: true
123125
- name: Install alsa and udev
124126
run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev
125-
- name: Check Benches
126-
run: cd benches && cargo check --benches
127+
- name: Check Compile
128+
# See tools/ci/src/main.rs for the commands this runs
129+
run: cargo run -p ci -- compile
127130

128131
build-wasm:
129132
strategy:
@@ -292,23 +295,36 @@ jobs:
292295

293296
check-doc:
294297
runs-on: ubuntu-latest
295-
needs: check-markdown-links
296-
if: always()
297298
steps:
298299
- uses: actions/checkout@v3
300+
- uses: actions/cache@v2
301+
with:
302+
path: |
303+
~/.cargo/bin/
304+
~/.cargo/registry/index/
305+
~/.cargo/registry/cache/
306+
~/.cargo/git/db/
307+
target/
308+
key: ${{ runner.os }}-check-doc-${{ hashFiles('**/Cargo.toml') }}
299309
- uses: actions-rs/toolchain@v1
300310
with:
301311
toolchain: stable
302312
- name: Install alsa and udev
303313
run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev libwayland-dev libxkbcommon-dev
304314
if: runner.os == 'linux'
305-
- name: Installs cargo-deadlinks
306-
run: cargo install --force cargo-deadlinks
307315
- name: Build and check doc
308-
run: RUSTDOCFLAGS='-D warnings' cargo doc --workspace --all-features --no-deps --document-private-items
309-
- name: Checks dead links
310-
run: cargo deadlinks --dir target/doc/bevy
311-
continue-on-error: true
316+
# See tools/ci/src/main.rs for the commands this runs
317+
run: cargo run -p ci -- doc
318+
env:
319+
CARGO_INCREMENTAL: 0
320+
RUSTFLAGS: "-C debuginfo=0"
321+
# This currently report a lot of false positives
322+
# Enable it again once it's fixed - https://github.com/bevyengine/bevy/issues/1983
323+
# - name: Installs cargo-deadlinks
324+
# run: cargo install --force cargo-deadlinks
325+
# - name: Checks dead links
326+
# run: cargo deadlinks --dir target/doc/bevy
327+
# continue-on-error: true
312328

313329
check-missing-examples-in-docs:
314330
runs-on: ubuntu-latest

CONTRIBUTING.md

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -280,10 +280,13 @@ If you're new to Bevy, here's the workflow we use:
280280
1. Fork the `bevyengine/bevy` repository on GitHub. You'll need to create a GitHub account if you don't have one already.
281281
2. Make your changes in a local clone of your fork, typically in its own new branch.
282282
1. Try to split your work into separate commits, each with a distinct purpose. Be particularly mindful of this when responding to reviews so it's easy to see what's changed.
283-
3. To test CI validations locally, run the `cargo run -p ci` command. You can also run sub-commands manually:
284-
1. `cargo fmt --all -- --check` (remove `--check` to let the command fix found problems)
285-
2. `cargo clippy --workspace --all-targets --all-features -- -D warnings -A clippy::type_complexity`
286-
3. `cargo test --all-targets --workspace`
283+
3. To test CI validations locally, run the `cargo run -p ci` command. This will run most checks that happen in CI, but can take some time. You can also run sub-commands to iterate faster depending on what you're contributing:
284+
* `cargo run -p ci -- lints` - to run formatting and clippy
285+
* `cargo run -p ci -- test` - to run tests
286+
* `cargo run -p ci -- doc` - to run doc tests and doc checks
287+
* `cargo run -p ci -- compile` - to check that everything that must compile still does (examples and benches), and that some that shouldn't still don't ([`crates/bevy_ecs_compile_fail_tests`](./crates/bevy_ecs_compile_fail_tests))
288+
* to get more informations on commands available and what is run, check the [tools/ci crate](./tools/ci)
289+
287290
4. When working with Markdown (`.md`) files, Bevy's CI will check markdown files (like this one) using [markdownlint](https://github.com/DavidAnson/markdownlint).
288291
To locally lint your files using the same workflow as our CI:
289292
1. Install [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli).

tools/ci/Cargo.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,4 @@ license = "MIT OR Apache-2.0"
88

99
[dependencies]
1010
xshell = "0.1"
11+
bitflags = "1.3"

tools/ci/src/main.rs

Lines changed: 75 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,99 @@
11
use xshell::{cmd, pushd};
22

3+
use bitflags::bitflags;
4+
5+
bitflags! {
6+
struct Check: u32 {
7+
const FORMAT = 0b00000001;
8+
const CLIPPY = 0b00000010;
9+
const COMPILE_FAIL = 0b00000100;
10+
const TEST = 0b00001000;
11+
const DOC_TEST = 0b00010000;
12+
const DOC_CHECK = 0b00100000;
13+
const BENCH_CHECK = 0b01000000;
14+
const EXAMPLE_CHECK = 0b10000000;
15+
}
16+
}
17+
318
fn main() {
419
// When run locally, results may differ from actual CI runs triggered by
520
// .github/workflows/ci.yml
621
// - Official CI runs latest stable
722
// - Local runs use whatever the default Rust is locally
823

9-
// See if any code needs to be formatted
10-
cmd!("cargo fmt --all -- --check")
11-
.run()
12-
.expect("Please run 'cargo fmt --all' to format your code.");
24+
let what_to_run = match std::env::args().nth(1).as_deref() {
25+
Some("format") => Check::FORMAT,
26+
Some("clippy") => Check::CLIPPY,
27+
Some("compile-fail") => Check::COMPILE_FAIL,
28+
Some("test") => Check::TEST,
29+
Some("doc-test") => Check::DOC_TEST,
30+
Some("doc-check") => Check::DOC_CHECK,
31+
Some("bench-check") => Check::BENCH_CHECK,
32+
Some("example-check") => Check::EXAMPLE_CHECK,
33+
Some("lints") => Check::FORMAT | Check::CLIPPY,
34+
Some("doc") => Check::DOC_TEST | Check::DOC_CHECK,
35+
Some("compile") => Check::COMPILE_FAIL | Check::BENCH_CHECK | Check::EXAMPLE_CHECK,
36+
_ => Check::all(),
37+
};
1338

14-
// See if clippy has any complaints.
15-
// - Type complexity must be ignored because we use huge templates for queries
16-
cmd!("cargo clippy --workspace --all-targets --all-features -- -D warnings -A clippy::type_complexity -W clippy::doc_markdown")
39+
if what_to_run.contains(Check::FORMAT) {
40+
// See if any code needs to be formatted
41+
cmd!("cargo fmt --all -- --check")
42+
.run()
43+
.expect("Please run 'cargo fmt --all' to format your code.");
44+
}
45+
46+
if what_to_run.contains(Check::CLIPPY) {
47+
// See if clippy has any complaints.
48+
// - Type complexity must be ignored because we use huge templates for queries
49+
cmd!("cargo clippy --workspace --all-targets --all-features -- -A clippy::type_complexity -W clippy::doc_markdown -D warnings")
1750
.run()
1851
.expect("Please fix clippy errors in output above.");
52+
}
1953

20-
// Run UI tests (they do not get executed with the workspace tests)
21-
// - See crates/bevy_ecs_compile_fail_tests/README.md
22-
{
54+
if what_to_run.contains(Check::COMPILE_FAIL) {
55+
// Run UI tests (they do not get executed with the workspace tests)
56+
// - See crates/bevy_ecs_compile_fail_tests/README.md
2357
let _bevy_ecs_compile_fail_tests = pushd("crates/bevy_ecs_compile_fail_tests")
2458
.expect("Failed to navigate to the 'bevy_ecs_compile_fail_tests' crate");
25-
cmd!("cargo test")
59+
cmd!("cargo test --target-dir ../../target")
2660
.run()
2761
.expect("Compiler errors of the ECS compile fail tests seem to be different than expected! Check locally and compare rust versions.");
2862
}
2963

30-
// These tests are already run on the CI
31-
// Using a double-negative here allows end-users to have a nicer experience
32-
// as we can pass in the extra argument to the CI script
33-
let args: Vec<String> = std::env::args().collect();
34-
if args.get(1) != Some(&"nonlocal".to_string()) {
35-
// Run tests
36-
cmd!("cargo test --workspace")
64+
if what_to_run.contains(Check::TEST) {
65+
// Run tests (except doc tests and without building examples)
66+
cmd!("cargo test --workspace --lib --bins --tests --benches")
3767
.run()
3868
.expect("Please fix failing tests in output above.");
69+
}
70+
71+
if what_to_run.contains(Check::DOC_TEST) {
72+
// Run doc tests
73+
cmd!("cargo test --workspace --doc")
74+
.run()
75+
.expect("Please fix failing doc-tests in output above.");
76+
}
77+
78+
if what_to_run.contains(Check::DOC_CHECK) {
79+
// Check that building docs work and does not emit warnings
80+
std::env::set_var("RUSTDOCFLAGS", "-D warnings");
81+
cmd!("cargo doc --workspace --all-features --no-deps --document-private-items")
82+
.run()
83+
.expect("Please fix doc warnings in output above.");
84+
}
85+
86+
if what_to_run.contains(Check::COMPILE_FAIL) {
87+
// Check that benches are building
88+
let _benches = pushd("benches").expect("Failed to navigate to the 'benches' folder");
89+
cmd!("cargo check --benches --target-dir ../target")
90+
.run()
91+
.expect("Failed to check the benches.");
92+
}
3993

40-
// Run doc tests: these are ignored by `cargo test`
41-
cmd!("cargo test --doc --workspace")
94+
if what_to_run.contains(Check::EXAMPLE_CHECK) {
95+
// Build examples and check they compile
96+
cmd!("cargo check --workspace --examples")
4297
.run()
4398
.expect("Please fix failing doc-tests in output above.");
4499
}

0 commit comments

Comments
 (0)