Contributing.md

   1 ## Contributing
   2
   3 ### Test and file issues
   4
   5 It would be really useful to have people use rustfmt on their projects and file
   6 issues where it does something you don't expect.
   7
   8 A really useful thing to do that on a crate from the Rust repo. If it does
   9 something unexpected, file an issue; if not, make a PR to the Rust repo with the
  10 reformatted code. We hope to get the whole repo consistently rustfmt'ed and to
  11 replace `make tidy` with rustfmt as a medium-term goal.
  12
  13 ### Create test cases
  14
  15 Having a strong test suite for a tool like this is essential. It is very easy
  16 to create regressions. Any tests you can add are very much appreciated.
  17
  18 The tests can be run with `cargo test`. This does a number of things:
  19 * runs the unit tests for a number of internal functions;
  20 * makes sure that rustfmt run on every file in `./tests/source/` is equal to its
  21   associated file in `./tests/target/`;
  22 * runs idempotence tests on the files in `./tests/target/`. These files should
  23   not be changed by rustfmt;
  24 * checks that rustfmt's code is not changed by running on itself. This ensures
  25   that the project bootstraps.
  26
  27 Creating a test is as easy as creating a new file in `./tests/source/` and an
  28 equally named one in `./tests/target/`. If it is only required that rustfmt
  29 leaves a piece of code unformatted, it may suffice to only create a target file.
  30
  31 Whenever there's a discrepancy between the expected output when running tests, a
  32 colourised diff will be printed so that the offending line(s) can quickly be
  33 identified.
  34
  35 Without explicit settings, the tests will be run using rustfmt's default
  36 configuration. It is possible to run a test using non-default settings by
  37 including configuration parameters in comments at the top of the file. For
  38 example: to use 3 spaces per tab, start your test with
  39 `// rustfmt-tab_spaces: 3`. Just remember that the comment is part of the input,
  40 so include in both the source and target files! It is also possible to
  41 explicitly specify the name of the expected output file in the target directory.
  42 Use `// rustfmt-target: filename.rs` for this. Finally, you can use a custom
  43 configuration by using the `rustfmt-config` directive. Rustfmt will then use
  44 that toml file located in `./tests/config/` for its configuration. Including
  45 `// rustfmt-config: small_tabs.toml` will run your test with the configuration
  46 file found at `./tests/config/small_tabs.toml`.
  47
  48 ### Hack!
  49
  50 Here are some [good starting issues](https://github.com/nrc/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3Aeasy).
  51 Note than some of those issues tagged 'easy' are not that easy and might be better
  52 second issues, rather than good first issues to fix.
  53
  54 If you've found areas which need polish and don't have issues, please submit a
  55 PR, don't feel there needs to be an issue.