diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b4a8af1f62..daaba78a0f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,16 +1,83 @@ # Contributing + ## New features -New features should go through the [RFC process][rfcs] before a Pull Request is made to this repository. + +New features should go through the [RFC process][rfcs] before creating a Pull Request to this repository. [rfcs](https://github.com/rtic-rs/rfcs) ## Bugs + Report bugs by creating an issue in this repository. -## Pull Requests +## Pull Requests (PRs) + Please make pull requests against the master branch. Always use rebase instead of merge when bringing in changes from master to your feature branch. ## Writing documentation -Documentation improvements are always welcome. The source for the book is in `book/` and API documentation is generated from the source code. + +Documentation improvements are always welcome. +The source for the book is in `book/` and API documentation is generated from the source code. + +## CI test preparation + +Continuous Integration (CI) tests are run against all pull requests. + +Please make sure that tests passes locally before submitting. + +### Cargo format + +```shell +> cargo fmt +``` + +### Example check + +```shell +> cargo check --examples --target thumbv7m-none-eabi +``` + +and/or + +```shell +> cargo check --examples --target thumbv6m-none-eabi +``` + +### Run tests with xtask + +```shell +> cargo xtask --target all +``` + +Will execute `run` tests on your local `qemu` install. +(You may also pass a single target `--target thumbv6m-none-eabi/thumbv7m-none-eabi` during development). + +#### Adding tests to xtask + +If you have added further tests, you need to add the expected output in the `ci/expected` folder. + +```shell +> cargo run --example --target thumbv7m-none-eabi > ci/expected/.run +``` + +### Internal tests + +Run internal fail tests locally with: + +```shell +> cargo test --tests +``` + +#### Adding tests to internal tests + +If you have added fail tests or changed the expected behavior, the expected output needs to be updated (corresponding `.stderr` files). +Inspect the error output, when sure that `ACTUAL OUTPUT` is correct you can re-run the test as: + +```shell +> TRYBUILD=overwrite cargo test --tests +``` + +This will update the expected output to match the `ACTUAL OUTPUT`. +Please check that the updated files are indeed correct to avoid regressions.