Skip to content

Commit c6ba0f7

Browse files
authored
Add more comprehensive documentation on testing and benchmarking to CONTRIBUTING.md (#5478)
* Add more testing and benchmarking documentation * remove extra line * Add benchmarking information --------- Co-authored-by: Clide Stefani <[email protected]>
1 parent ae1d10f commit c6ba0f7

File tree

1 file changed

+53
-5
lines changed

1 file changed

+53
-5
lines changed

CONTRIBUTING.md

Lines changed: 53 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -92,19 +92,31 @@ export ARROW_TEST_DATA=$(cd ../testing/data; pwd)
9292

9393
From here on, this is a pure Rust project and `cargo` can be used to run tests, benchmarks, docs and examples as usual.
9494

95-
### Running the tests
95+
## Running the tests
9696

9797
Run tests using the Rust standard `cargo test` command:
9898

9999
```bash
100-
# run all tests.
100+
# run all unit and integration tests
101101
cargo test
102102

103-
104-
# run only tests for the arrow crate
103+
# run tests for the arrow crate
105104
cargo test -p arrow
106105
```
107106

107+
For some changes, you may want to run additional tests. You can find up-to-date information on the current CI tests in [.github/workflows](https://github.com/apache/arrow-rs/tree/master/.github/workflows). Here are some examples of additional tests you may want to run:
108+
109+
```bash
110+
# run tests for the parquet crate
111+
cargo test -p parquet
112+
113+
# run arrow tests with all features enabled
114+
cargo test -p arrow --all-features
115+
116+
# run the doc tests
117+
cargo test --doc
118+
```
119+
108120
## Code Formatting
109121

110122
Our CI uses `rustfmt` to check code formatting. Before submitting a
@@ -118,10 +130,19 @@ cargo +stable fmt --all -- --check
118130

119131
We recommend using `clippy` for checking lints during development. While we do not yet enforce `clippy` checks, we recommend not introducing new `clippy` errors or warnings.
120132

121-
Run the following to check for clippy lints.
133+
Run the following to check for `clippy` lints:
122134

123135
```bash
136+
# run clippy with default settings
124137
cargo clippy
138+
139+
```
140+
141+
More comprehensive `clippy` checks can be run by adding flags:
142+
143+
```bash
144+
# run clippy on the arrow crate with all features enabled, targeting all tests, examples, and benchmarks
145+
cargo clippy -p arrow --all-features --all-targets
125146
```
126147

127148
If you use Visual Studio Code with the `rust-analyzer` plugin, you can enable `clippy` to run each time you save a file. See https://users.rust-lang.org/t/how-to-use-clippy-in-vs-code-with-rust-analyzer/41881.
@@ -134,6 +155,33 @@ Search for `allow(clippy::` in the codebase to identify lints that are ignored/a
134155
- If you have several lints on a function or module, you may disable the lint on the function or module.
135156
- If a lint is pervasive across multiple modules, you may disable it at the crate level.
136157

158+
## Running Benchmarks
159+
160+
Running benchmarks are a good way to test the performance of a change. As benchmarks usually take a long time to run, we recommend running targeted tests instead of the full suite.
161+
162+
```bash
163+
# run all benchmarks
164+
cargo bench
165+
166+
# run arrow benchmarks
167+
cargo bench -p arrow
168+
169+
# run benchmark for the parse_time function within the arrow-cast crate
170+
cargo bench -p arrow-cast --bench parse_time
171+
```
172+
173+
To set the baseline for your benchmarks, use the --save-baseline flag:
174+
175+
```bash
176+
git checkout master
177+
178+
cargo bench --bench parse_time -- --save-baseline master
179+
180+
git checkout feature
181+
182+
cargo bench --bench parse_time -- --baseline master
183+
```
184+
137185
## Git Pre-Commit Hook
138186

139187
We can use [git pre-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) to automate various kinds of git pre-commit checking/formatting.

0 commit comments

Comments
 (0)