vendor/gimli/CONTRIBUTING.md

   1 # Contributing to `gimli`
   2
   3 Hi! We'd love to have your contributions! If you want help or mentorship, reach
   4 out to us in a GitHub issue, or ping `fitzgen` in `#rust` on `irc.mozilla.org`.
   5
   6 * [Code of Conduct](#coc)
   7 * [Filing an Issue](#issues)
   8 * [Building `gimli`](#building)
   9 * [Testing `gimli`](#testing)
  10   * [Test Coverage](#coverage)
  11   * [Using `test-assembler`](#test-assembler)
  12   * [Fuzzing](#fuzzing)
  13 * [Benchmarking](#benchmarking)
  14 * [Style](#style)
  15
  16 ## <a id="coc"></a> Code of Conduct
  17
  18 We abide by the
  19 [Rust Code of Conduct](https://www.rust-lang.org/en-US/conduct.html) and ask
  20 that you do as well.
  21
  22 ## <a id="issues"></a> Filing an Issue
  23
  24 Think you've found a bug? File an issue! To help us understand and reproduce the
  25 issue, provide us with:
  26
  27 * The (preferably minimal) test case
  28 * Steps to reproduce the issue using the test case
  29 * The expected result of following those steps
  30 * The actual result of following those steps
  31
  32 Definitely file an issue if you see an unexpected panic originating from within
  33 `gimli`! `gimli` should never panic unless it is explicitly documented to panic
  34 in the specific circumstances provided.
  35
  36 ## <a id="building"></a> Building `gimli`
  37
  38 `gimli` should always build on stable `rustc`, but we recommend using
  39 [`rustup`](https://www.rustup.rs/) so you can switch to nightly `rustc` and run
  40 benchmarks.
  41
  42 To build `gimli`:
  43
  44 ```
  45 $ cargo build
  46 ```
  47
  48 ## <a id="testing"></a> Testing `gimli`
  49
  50 Run the tests with `cargo`:
  51
  52 ```
  53 $ cargo test
  54 ```
  55
  56 ### <a id="coverage"></a> Test Coverage
  57
  58 If you have `kcov` installed under linux, then you can generate code coverage
  59 results using the `coverage` script in the root of the repository, and view them
  60 at `target/kcov/index.html`. Otherwise you can create a pull request and view
  61 the coverage results on coveralls.io.
  62
  63 ```
  64 $ ./coverage
  65 ```
  66
  67 The ideal we aim to reach is having our unit tests exercise every branch in
  68 `gimli`. We allow an exception for branches which propagate errors inside a
  69 `try!(..)` invocation, but we *do* want to exercise the original error paths.
  70
  71 Pull requests adding new code should ensure that this ideal is met.
  72
  73 At the time of writing we have 94% test coverage according to our coveralls.io
  74 continuous integration. That number should generally stay the same or go up ;)
  75 This is a bit subjective, because -.001% is just noise and doesn't matter.
  76
  77 ### <a id="test-assembler"></a> Using `test-assembler`
  78
  79 We use the awesome
  80 [`test-assembler`](https://github.com/luser/rust-test-assembler) crate to
  81 construct binary test data. It makes building complex test cases readable.
  82
  83 [Here is an example usage in `gimli`](https://github.com/gimli-rs/gimli/blob/156451f3fe6eeb2fa62b84b362c33fcb176e1171/src/loc.rs#L263)
  84
  85 ### <a id="fuzzing"></a> Fuzzing
  86
  87 First, install `cargo fuzz`:
  88
  89 ```
  90 $ cargo install cargo-fuzz
  91 ```
  92
  93 Optionally, [set up the corpora for our fuzz targets by following these
  94 instructions](https://github.com/gimli-rs/gimli-libfuzzer-corpora/blob/master/README.md#using-these-corpora).
  95
  96 Finally, run a fuzz target! In this case, we are running the `eh_frame` fuzz
  97 target:
  98
  99 ```
 100 $ cargo fuzz run eh_frame
 101 ```
 102
 103 The fuzz target definitions live in `fuzz/fuzz_targets/*`. You can add new ones
 104 via `cargo fuzz add <my_new_target>`.
 105
 106 ## <a id="benchmarking"></a> Benchmarking
 107
 108 The benchmarks require nightly `rustc`, so use `rustup`:
 109
 110 ```
 111 $ rustup run nightly cargo bench
 112 ```
 113
 114 We aim to be the fastest DWARF library. Period.
 115
 116 Please provide before and after benchmark results with your pull requests. You
 117 may also find [`cargo benchcmp`](https://github.com/BurntSushi/cargo-benchcmp)
 118 handy for comparing results.
 119
 120 Pull requests adding `#[bench]` micro-benchmarks that exercise a new edge case
 121 are very welcome!
 122
 123 ## <a id="style"></a> Style
 124
 125 We use `rustfmt` to automatically format and style all of our code.
 126
 127 To install `rustfmt`:
 128
 129 ```
 130 $ rustup component add rustfmt-preview
 131 ```
 132
 133 To run `rustfmt` on `gimli`:
 134
 135 ```
 136 $ cargo fmt
 137 ```