Merge #598

598: CONTRIBUTION.md now includes CI prep. r=korken89 a=AfoHT

Split out from Per’s previous work in `lockall` branch with some minor updates


Co-authored-by: Per Lindgren <per.lindgren@ltu.se>

1 files changed, 70 insertions, 3 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b4a8af1f..daaba78a 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 <NAME> --target thumbv7m-none-eabi > ci/expected/<NAME>.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.