diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7681ef9da..8e9716c11 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -197,8 +197,22 @@ If the change being proposed alters code (as opposed to only documentation for example), it is either adding new functionality to Tokio or it is fixing existing, broken functionality. In both of these cases, the pull request should include one or more tests to ensure that Tokio does not regress in the future. -There are two ways to write tests: integration tests and documentation tests -(Tokio avoids unit tests as much as possible). +There are two ways to write tests: [integration tests][integration-tests] +and [documentation tests][documentation-tests]. +(Tokio avoids [unit tests][unit-tests] as much as possible). + +Tokio uses [conditional compilation attributes][conditional-compilation] +throughout the codebase, to modify rustc's behavior. Code marked with such +attributes can be enabled using RUSTFLAGS and RUSTDOCFLAGS environment +variables. One of the most prevalent flags passed in these variables is +the `--cfg` option. To run tests in a particular file, check first what +options #![cfg] declaration defines for that file. + +For instance, to run a test marked with the 'tokio_unstable' cfg option, +you must pass this flag to the compiler when running the test. +``` +$ RUSTFLAGS="--cfg tokio_unstable" cargo test -p tokio --all-features --test rt_metrics +``` #### Integration tests @@ -658,3 +672,7 @@ When releasing a new version of a crate, follow these steps: entry for that release version into your editor and close the window. [keep-a-changelog]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md +[unit-tests]: https://doc.rust-lang.org/rust-by-example/testing/unit_testing.html +[integration-tests]: https://doc.rust-lang.org/rust-by-example/testing/integration_testing.html +[documentation-tests]: https://doc.rust-lang.org/rust-by-example/testing/doc_testing.html +[conditional-compilation]: https://doc.rust-lang.org/reference/conditional-compilation.html \ No newline at end of file