docs: update build/test/install instructions

Author: calebcartwright

Contributing.md

@@ -14,40 +14,73 @@ Conduct](CODE_OF_CONDUCT.md).
 Rustfmt requires a nightly compiler. Replace all invocations of `cargo` by
 `cargo +nightly` if necessary.
 
-At all times the environment variables `CFG_RELEASE_CHANNEL` and `CFG_RELEASE` must
-be set to either `nightly` or `beta`. Both should be set to the same value. The
-project supports [cargo-make](https://github.com/sagiegurari/cargo-make) which
-automatically sets these variables for you:
+At all times the environment variables `CFG_RELEASE_CHANNEL` and `CFG_RELEASE` must be set. `CFG_RELEASE_CHANNEL` must be set to either `nightly` or `beta`, and `CFG_RELEASE` should be set to your corresponding Rust version. The
+project supports and recommends [cargo-make][cargo-make] when working on rustfmt, because `cargo-make` automatically sets these variables for you
 
+The available tasks are listed in `Makefile.toml`.
+
+You can alternatively use `cargo` directly, but you'll have to set the `CFG_RELEASE` and `CFG_RELEASE_CHANNEL` environment variables and also provide the corresponding features.
+
+For example:
+```sh
+export CFG_RELEASE=1.45.0-nightly
+export CFG_RELEASE=nightly
 ```
-cargo +nightly make test
+(Windows users can use `set` to specify the environment variable values)
+
+## Building
+To build with `cargo make`:
+
+```sh
+cargo make build
 ```
 
-The available tasks are listed in `Makefile.toml`.
+Or alternatively with `cargo` directly:
+```sh
+cargo build --all-features
+# or
+CFG_RELEASE_CHANNEL=nightly CFG_RELEASE=1.45.0-nightly cargo build --all-features
+```
 
 ## Test and file issues
 
 It would be really useful to have people use rustfmt on their projects and file
 issues where it does something you don't expect.
 
 
-## Create test cases
+## Running tests
 
-Having a strong test suite for a tool like this is essential. It is very easy
-to create regressions. Any tests you can add are very much appreciated.
+The tests can be executed with `cargo make` or directly with `cargo` provided the corresponding environment variables have been set.
 
-The tests can be run with `cargo make test`. This does a number of things:
+To run tests with `cargo make`:
+
+```sh
+cargo make test
+```
+
+Or alternatively with `cargo` directly:
+```sh
+cargo test --all-features
+# or 
+CFG_RELEASE_CHANNEL=nightly CFG_RELEASE=1.45.0-nightly cargo test --all-features
+```
+
+This does a number of things:
 * runs the unit tests for a number of internal functions;
-* makes sure that rustfmt run on every file in `rustfmt-core/rustfmt-lib/tests/source/`
-  is equal to its associated file in `rustfmt-core/rustfmt-lib/tests/target/`;
-* runs idempotence tests on the files in `rustfmt-core/rustfmt-lib/tests/target/`.
+* makes sure that rustfmt run on every file in `tests/source/`
+  is equal to its associated file in `tests/target/`;
+* runs idempotence tests on the files in `tests/target/`.
   These files should not be changed by rustfmt;
 * checks that rustfmt's code is not changed by running on itself. This ensures
   that the project bootstraps.
 
+## Creating test cases
+Having a strong test suite for a tool like this is essential. It is very easy
+to create regressions. Any tests you can add are very much appreciated.
+
 Creating a test is as easy as creating a new file in
-`rustfmt-core/rustfmt-lib/tests/source/` and an equally named one in
-`rustfmt-core/rustfmt-lib/tests/target/`. If it is only required that rustfmt leaves a
+`tests/source/` and an equally named one in
+`tests/target/`. If it is only required that rustfmt leaves a
 piece of code unformatted, it may suffice to only create a target file.
 
 Whenever there's a discrepancy between the expected output when running tests, a
@@ -73,6 +106,8 @@ would need a configuration file named `test-indent.toml` in that directory. As a
 example, the `issue-1111.rs` test file is configured by the file
 `./tests/config/issue-1111.toml`.
 
+[cargo-make]: https://sagiegurari.github.io/cargo-make/
+
 ## Debugging
 
 Some `rewrite_*` methods use the `debug!` macro for printing useful information.
@@ -82,7 +117,13 @@ and get a better grasp on the execution flow.
 
 ## Hack!
 
-Here are some [good starting issues](https://github.com/rust-lang/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3Agood-first-issue).
+There are a lot of open issues on the backlog for those interested in hacking on rustfmt. If you find an issue that you are interested in working on, add a comment to the issue to let us (and other potential contributors) know!
+
+Here are some good starting issues:
+
+[![GitHub good-first-issue](https://img.shields.io/github/issues/rust-lang/rustfmt/good-first-issue?style=flat-square)](https://github.com/rust-lang/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3Agood%20first%20issue)
+[![GitHub help-wanted](https://img.shields.io/github/issues/rust-lang/rustfmt/help-wanted?style=flat-square)](https://github.com/rust-lang/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3Ahelp-wanted)
+
 
 If you've found areas which need polish and don't have issues, please submit a
 PR, don't feel there needs to be an issue.
@@ -95,7 +136,7 @@ source code. So, basically, the only style guideline is that you must pass the
 tests. That ensures that the Rustfmt source code adheres to our own conventions.
 
 Talking of tests, if you add a new feature or fix a bug, please also add a test.
-It's really easy, see above for details. Please run `cargo test` before
+It's really easy, see above for details. Please [run the tests](#running-tests) locally before
 submitting a PR to ensure your patch passes all tests, it's pretty quick.
 
 Rustfmt is post-1.0 and within major version releases we strive for backwards

README.md

@@ -1,4 +1,4 @@
-# rustfmt [![Build Status](https://travis-ci.com/rust-lang/rustfmt.svg?branch=master)](https://travis-ci.com/rust-lang/rustfmt) [![Build Status](https://ci.appveyor.com/api/projects/status/github/rust-lang/rustfmt?svg=true)](https://ci.appveyor.com/project/rust-lang-libs/rustfmt) [![crates.io](https://img.shields.io/crates/v/rustfmt-nightly.svg)](https://crates.io/crates/rustfmt-nightly) [![Travis Configuration Status](https://img.shields.io/travis/davidalber/rustfmt-travis.svg?label=travis%20example)](https://travis-ci.org/davidalber/rustfmt-travis)
+# rustfmt [![Linux badge][linux-build-status]][linux-build] [![Mac badge][mac-build-status]][mac-build] [![Windows badge][windows-build-status]][windows-build] [![crates.io badge][cratesio-badge]][cratesio-package] [![Travis config badge][travis-config-badge]][travis-config-job]
 
 A tool for formatting Rust code according to style guidelines.
 
@@ -82,11 +82,22 @@ rustup component add rustfmt
 
 ## Installing from source
 
-To install from source (nightly required), first checkout to the tag or branch you want to install, then issue
+To install from source (nightly required), first checkout to the tag or branch for the version of rustfmt you want. 
+
+The easiest way to install is via [cargo make][cargo-make]
+
+```sh
+cargo make install
+```
+
+Alternatively, you can run `cargo install` directly as long as you set the required environment variables and features.
 
 ```sh
-cargo install --path .
+export CFG_RELEASE=1.45.0-nightly
+export CFG_RELEASE=nightly
+cargo install --path . --force --locked --features rustfmt,cargo-fmt
 ```
+(Windows users can use `set` to specify the environment variable values)
 
 This will install `rustfmt` in your `~/.cargo/bin`. Make sure to add `~/.cargo/bin` directory to
 your PATH variable.
@@ -146,9 +157,42 @@ for more info.
 
 ## How to build and test
 
-`cargo build` to build.
+We recommend using [cargo make][cargo-make] when working with the rustfmt codebase.
+
+You can alternatively use `cargo` directly, but you'll have to set the `CFG_RELEASE` and `CFG_RELEASE_CHANNEL` environment variables and also provide the corresponding features.
+
+For example:
+```sh
+export CFG_RELEASE=1.45.0-nightly
+export CFG_RELEASE=nightly
+```
+(Windows users can use `set` to specify the environment variable values)
+
+To build with `cargo make`:
+
+```sh
+cargo make build
+```
+
+Or alternatively with `cargo` directly:
+```sh
+cargo build --all-features
+# or
+CFG_RELEASE_CHANNEL=nightly CFG_RELEASE=1.45.0-nightly cargo build --all-features
+```
+
+To run tests with `cargo make`:
 
-`cargo test --manifest-path rustfmt-core/Cargo.toml` to run all tests.
+```sh
+cargo make test
+```
+
+Or alternatively with `cargo` directly:
+```sh
+cargo test --all-features
+# or 
+CFG_RELEASE_CHANNEL=nightly CFG_RELEASE=1.45.0-nightly cargo test --all-features
+```
 
 To run rustfmt after this, use `cargo run --bin rustfmt -- filename`. See the
 notes above on running rustfmt.
@@ -231,3 +275,14 @@ See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details.
 [rust]: https://github.com/rust-lang/rust
 [fmt rfcs]: https://github.com/rust-lang-nursery/fmt-rfcs
 [style guide]: https://github.com/rust-lang-nursery/fmt-rfcs/blob/master/guide/guide.md
+[cargo-make]: https://sagiegurari.github.io/cargo-make/
+[linux-build-status]: https://img.shields.io/github/workflow/status/rust-lang/rustfmt/linux/master?label=linux&style=flat-square
+[linux-build]: https://github.com/rust-lang/rustfmt/actions?query=workflow%3Alinux+branch%3Amaster
+[mac-build-status]: https://img.shields.io/github/workflow/status/rust-lang/rustfmt/mac/master?label=mac&style=flat-square
+[mac-build]: https://github.com/rust-lang/rustfmt/actions?query=workflow%3Amac+branch%3Amaster
+[windows-build-status]: https://img.shields.io/github/workflow/status/rust-lang/rustfmt/windows/master?label=windows&style=flat-square
+[windows-build]: https://github.com/rust-lang/rustfmt/actions?query=workflow%3Awindows+branch%3Amaster
+[cratesio-badge]: https://img.shields.io/crates/v/rustfmt-nightly?style=flat-square
+[cratesio-package]: https://crates.io/crates/rustfmt-nightly
+[travis-config-badge]: https://img.shields.io/travis/davidalber/rustfmt-travis?label=travis%20example&style=flat-square
+[travis-config-job]: https://travis-ci.org/davidalber/rustfmt-travis