Merge assert-rs#71

71: Improve the state of docs for new users r=killercup a=epage

Author: bors[bot]

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,11 @@
+<!--
+Hi! If you want to report a bug, request a feature, or ask a question on how to
+use assert_cli, you have come to the right place!
+
+If you want to report a bug, please fill in the following. Otherwise, feel free
+to remove these lines.
+-->
+
+- `assert_cli` version:
+- Rust version:
+- OS and version:

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+<!--
+Thank you for taking the time to contribute to this project!
+
+To ease reviewing your changes and making sure we don't forget anything,  please
+take a minute to check the following (remove lines that don't apply), and
+replace this text with a description of what this PR does. Bonus points for
+linking to issues! :)
+-->
+
+- [ ] I have created tests for any new feature, or added regression tests for bugfixes.
+- [ ] `cargo test` succeeds
+- [ ] Clippy is happy: `cargo +nightly clippy` succeeds
+- [ ] Rustfmt is happy: `cargo +nightly fmt` succeeds

CONTRIBUTING.md

@@ -0,0 +1,32 @@
+Thanks for wanting to contribute!
+
+Feel free to create issues or make pull requests, we'll try to quickly review them.
+
+If you need to reach out to us, find a relevant [issue][Issues] or open a new one.
+
+# Pull Requests
+
+## Project Ideas
+
+If you're looking for things to do check out the [open issues][Issues].
+Or take a grep through [all TODO comments][TODO] in the code and feel free to help us out there!
+
+## Best Practices
+
+We appreciate your help as-is. We'd love to help you through the process for contributing. We have some suggestions to help make things go more smoothly.
+
+Before spending too much time on a PR, consider opening an issue so we can make sure we're aligned on how the problem should be solved.
+
+# Releasing
+
+When we're ready to release, a project owner should do the following
+- Determine what the next version is, according to semver
+- Update the version in `Cargo.toml` and in the `README.md` and commit
+- Run `git tag v<X>.<Y>.<Z>`
+- Push all of this to `master`
+- Create a github release
+  - Identify what fixes, features, and breaking changes are in the release.
+- Run `cargo publish` (run `cargo login` first if needed)
+
+[Issues]: https://github.com/killercup/assert_cli/issues
+[TODO]: https://github.com/killercup/assert_cli/search?q=TODO

Cargo.toml

@@ -9,7 +9,7 @@ homepage = "https://github.com/killercup/assert_cli"
 documentation = "http://docs.rs/assert_cli/"
 readme = "README.md"
 categories = ["development-tools::testing"]
-keywords = ["cli", "testing", "assert"]
+keywords = ["cli", "testing", "assert", "command-line-interface"]
 build = "build.rs"
 
 [[bin]]

README.md

@@ -2,57 +2,48 @@
 
 > **Test CLI Applications** - This crate checks the output of a child process is as expected.
 
-[![Build Status](https://travis-ci.org/killercup/assert_cli.svg)](https://travis-ci.org/killercup/assert_cli) [![Documentation](https://img.shields.io/badge/docs-master-blue.svg)][Documentation]
+[![Build Status](https://travis-ci.org/killercup/assert_cli.svg)][Travis]
+[![Documentation](https://img.shields.io/badge/docs-master-blue.svg)][Documentation]
+![License](https://img.shields.io/crates/l/assert_cli.svg)
+[![crates.io](https://img.shields.io/crates/v/assert_cli.svg)][Crates.io]
 
 ## Install
 
-Just add it to your `Cargo.toml`:
+For your tests, add it to your `Cargo.toml`:
 
 ```toml
-[dependencies]
+[dev-dependencies]
 assert_cli = "0.5"
 ```
 
 ## Example
 
 Here's a trivial example:
 
-```rust
+```rust,ignore
 extern crate assert_cli;
 
 fn main() {
-    assert_cli::Assert::command(&["echo", "42"]).stdout().contains("42").unwrap();
-}
-```
-
-Or if you'd rather use the macro, to save you some writing:
-
-```rust
-#[macro_use] extern crate assert_cli;
-
-fn main() {
-    assert_cmd!(echo "42").stdout().contains("42").unwrap();
+    assert_cli::Assert::main_binary().unwrap();
 }
 ```
 
-And here is one that will fail (which also shows `execute` which returns a
-`Result` and can be used instead of `unwrap`):
+And here is one that will fail (and demonstrates running arbitrary commands):
 
 ```rust
-#[macro_use] extern crate assert_cli;
+extern crate assert_cli;
 
 fn main() {
-    let test = assert_cmd!(ls "foo-bar-foo")
+    assert_cli::Assert::command(&["ls", "foo-bar-foo"])
         .fails()
         .and()
         .stderr().contains("foo-bar-foo")
-        .execute();
-    assert!(test.is_ok());
+        .unwrap();
 }
 ```
 
 If you want to match the program's output _exactly_, you can use
-`stdout().is`:
+`stdout().is` (and shows the macro form of `command`):
 
 ```rust,should_panic
 #[macro_use] extern crate assert_cli;
@@ -80,6 +71,13 @@ Assert Cli use [Environment][Environment] underneath to deal with environment va
 
 More detailed information is available in the [documentation]. :-)
 
+## Relevant crates
+
+Other crates that might be useful in testing command line programs.
+* [dir-diff][dir-diff] for testing file side-effects.
+* [tempdir][tempdir] for scratchpad directories.
+* [duct][duct] for orchestrating multiple processes.
+
 ## License
 
 Licensed under either of
@@ -96,5 +94,10 @@ submitted for inclusion in the work by you, as defined in the Apache-2.0
 license, shall be dual licensed as above, without any additional terms or
 conditions.
 
+[Travis]: https://travis-ci.org/killercup/assert_cli
+[Crates.io]: https://crates.io/crates/assert_cli
 [Documentation]: https://docs.rs/assert_cli
 [Environment]: https://github.com/Freyskeyd/environment
+[dir-diff]: https://crates.io/crates/dir-diff
+[tempdir]: https://crates.io/crates/tempdir
+[duct]: https://crates.io/crates/duct

src/assert.rs

@@ -176,8 +176,10 @@ impl Assert {
     /// ```rust
     /// extern crate assert_cli;
     ///
-    /// assert_cli::Assert::command(&["echo", "42"])
-    ///     .stdout().contains("42")
+    /// assert_cli::Assert::command(&["cat", "non-existing-file"])
+    ///     .fails()
+    ///     .and()
+    ///     .stderr().contains("non-existing-file")
     ///     .unwrap();
     /// ```
     pub fn and(self) -> Self {
@@ -192,6 +194,7 @@ impl Assert {
     /// extern crate assert_cli;
     ///
     /// assert_cli::Assert::command(&["echo", "42"])
+    ///     .succeeds()
     ///     .unwrap();
     /// ```
     pub fn succeeds(mut self) -> Self {