Repository: elastic-rs/elastic (language: rust)

Issue:
Add readme to `elastic`
The crates.io page looks a bit sad without a readme. We'll probably need to add a specific one to the `/src/elastic` folder to include in the `Cargo.toml`.


Discussion / hints:

Fix patch:
diff --git a/README.md b/README.md
index 5c9221f3d0..28e15c0dca 100644
--- a/README.md
+++ b/README.md
@@ -18,17 +18,17 @@ This crate is still quite unstable and is likely to continue to churn breaking r
 If you run into any problems upgrading in your own open source projects feel free to [open up an issue](https://github.com/elastic-rs/elastic/issues) and we'll give you a hand. The goal is definitely to offer a stable API eventually.
 
 ## Build Status
-Platform  | Channel | Status
-------------- | ------------- | -------------
-Linux / OSX  | Stable/Nightly | [![Build Status](https://travis-ci.org/elastic-rs/elastic.svg?branch=master)](https://travis-ci.org/elastic-rs/elastic)
-Windows  | Nightly | [![Build status](https://ci.appveyor.com/api/projects/status/csa78tcumdpnbur2?svg=true)](https://ci.appveyor.com/project/KodrAus/elastic)
+Platform  | Channel | Status (`master`) | Status (`vNext`)
+------------- | ------------- | ------------- | ------------
+Linux / OSX  | Stable/Nightly | [![Build Status](https://travis-ci.org/elastic-rs/elastic.svg?branch=master)](https://travis-ci.org/elastic-rs/elastic) | [![Build Status](https://travis-ci.org/elastic-rs/elastic.svg?branch=vNext)](https://travis-ci.org/elastic-rs/elastic)
+Windows  | Nightly | [![Build status](https://ci.appveyor.com/api/projects/status/csa78tcumdpnbur2?svg=true)](https://ci.appveyor.com/project/KodrAus/elastic) | [![Build status](https://ci.appveyor.com/api/projects/status/csa78tcumdpnbur2/branch/vNext?svg=true)](https://ci.appveyor.com/project/KodrAus/elastic/branch/vNext)
 
 ## Documentation
 
 Version                | Docs
 ---------------------- | -------------
 current (`master`)     | [![Documentation](https://img.shields.io/badge/docs-rustdoc-blue.svg)](https://docs.rs/elastic/*/elastic/)
-`vNext`                | [![Documentation](https://img.shields.io/badge/docs-rustdoc-orange.svg)](http://elastic-rs.github.io/elastic/elastic/index.html)
+unstable `vNext`       | [![Documentation](https://img.shields.io/badge/docs-rustdoc-orange.svg)](http://elastic-rs.github.io/elastic/elastic/index.html)
 
 ## Example
 
@@ -125,6 +125,14 @@ The `elastic` crate brings a few independent crates together into a cohesive API
 
 There hasn't been much effort put into abstracting these dependencies at this stage, and `elastic` can't stabilise until these libraries and a few others do.
 
+### Branches
+
+The `master` branch should always be just about current with what's released on `crates.io`. Any non-breaking changes will be merged straight into `master` and released.
+
+The `vNext` branch is where breaking changes for upcoming releases are collected. Once we're ready for a new breaking release, we'll merge `vNext` into `master` and push out a new release.
+
+If you'd like to work on a new feature, base off `master`, unless you depend on code that's already in `vNext`. If the feature can be implemented in a non-breaking way then we'll merge it in to `master` for you. If it can't then we'll merge it in to `vNext`.
+
 ### Methodology
 
 The following is a simple set of guidelines that the codebase should follow. It's mostly a reminder to ourselves and not a hard set of rules.
diff --git a/src/elastic/Cargo.toml b/src/elastic/Cargo.toml
index 8b4a8c9163..9b4c7ed56f 100644
--- a/src/elastic/Cargo.toml
+++ b/src/elastic/Cargo.toml
@@ -1,12 +1,13 @@
 [package]
 name = "elastic"
-version = "0.20.0"
+version = "0.20.1"
 authors = ["Ashley Mannix <ashleymannix@live.com.au>"]
 license = "Apache-2.0"
 keywords = ["elasticsearch", "search"]
 description = "A modular sync and async client for the Elasticsearch REST API."
 documentation = "https://docs.rs/elastic/"
 repository = "https://github.com/elastic-rs/elastic"
+readme = "README.md"
 
 [badges]
 travis-ci = { repository = "elastic-rs/elastic" }
diff --git a/src/elastic/README.md b/src/elastic/README.md
new file mode 100644
index 0000000000..1211e55cd9
--- /dev/null
+++ b/src/elastic/README.md
@@ -0,0 +1,91 @@
+# [`elastic`](https://docs.rs/elastic/*/elastic/) [![Latest Version](https://img.shields.io/crates/v/elastic.svg)](https://crates.io/crates/elastic) [![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/elastic-rs/Lobby)
+
+`elastic` is an efficient, modular API client for [Elasticsearch](https://github.com/elastic/elasticsearch) written in [Rust](https://www.rust-lang.org).
+The API is targeting the Elastic Stack `5.x`.
+
+`elastic` provides strongly-typed documents and weakly-typed queries.
+
+## Stability
+
+This crate is still quite unstable and is likely to continue to churn breaking releases over the near future with not-so-detailed changelogs.
+
+If you run into any problems upgrading in your own open source projects feel free to [open up an issue](https://github.com/elastic-rs/elastic/issues) and we'll give you a hand. The goal is definitely to offer a stable API eventually.
+
+## Example
+
+Add `elastic` to your `Cargo.toml`:
+
+```toml
+[dependencies]
+elastic = "*"
+elastic_derive = "*"
+serde_json = "*"
+```
+
+Create a `SyncClient` and start making requests:
+
+```rust
+#[macro_use]
+extern crate elastic_derive;
+#[macro_use]
+extern crate serde_json;
+extern crate elastic;
+
+use serde_json::Value;
+use elastic::prelude::*;
+
+// A reqwest HTTP client and default parameters.
+// The builder includes the base node url (http://localhost:9200).
+let client = SyncClientBuilder::new().build()?;
+
+let query = "some query string";
+
+// A search request with a freeform body.
+let res = client.search::<Value>()
+                .index("_all")
+                .body(json!({
+                    "query": {
+                        "query_string": {
+                            "query": query
+                        }
+                    }
+                }))
+                .send()?;
+
+// Iterate through the hits in the response.
+for hit in res.hits() {
+    println!("{:?}", hit);
+}
+```
+
+`elastic` also offers an `AsyncClient` for use with the `tokio` asynchronous io stack.
+See the [examples](https://github.com/elastic-rs/elastic/tree/master/examples) folder for complete samples.
+
+### Building documents
+
+Document mapping is derived at compile-time from your _Plain Old Rust Structures_. Just add a `#[derive(ElasticType)]` attribute:
+
+```rust
+#[derive(ElasticType, Serialize, Deserialize)]
+struct MyDocument {
+	pub id: i32,
+	pub title: String,
+	pub timestamp: Date<DefaultDateMapping<EpochMillis>>,
+	pub content: Text<DefaultTextMapping>,
+}
+```
+
+And you can start using `MyDocument` in `Client` request methods.
+
+See the [docs](https://docs.rs/elastic/*/elastic/types/index.html) for more details.
+
+## Alternatives
+
+If you'd like to use a strongly-typed Query DSL builder see [`rs-es`](https://github.com/benashford/rs-es). This client does the hard work of providing an idiomatic Rust API for interacting with Elasticsearch. It has the advantage of letting you know your queries will parse at compile-time instead of runtime.
+
+## License
+
+Licensed under either of these:
+ 
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
diff --git a/src/elastic_derive/Cargo.toml b/src/elastic_derive/Cargo.toml
index d7f008a5e6..f458711117 100644
--- a/src/elastic_derive/Cargo.toml
+++ b/src/elastic_derive/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "elastic_derive"
-version = "0.20.0"
+version = "0.20.1"
 authors = ["Ashley Mannix <ashleymannix@live.com.au>"]
 license = "Apache-2.0"
 description = "Compile-time code generation for Elasticsearch type implementations."
diff --git a/src/requests/Cargo.toml b/src/requests/Cargo.toml
index 51464b8e93..27217c7151 100644
--- a/src/requests/Cargo.toml
+++ b/src/requests/Cargo.toml
@@ -1,10 +1,11 @@
 [package]
 name = "elastic_requests"
-version = "0.20.0"
+version = "0.20.1"
 authors = ["Ashley Mannix <ashleymannix@live.com.au>"]
 license = "Apache-2.0"
 description = "Code generated request types for the Elasticsearch REST API."
 documentation = "https://docs.rs/elastic_requests/"
 repository = "https://github.com/elastic-rs/elastic"
+readme = "README.md"
 
 [dependencies]
diff --git a/src/reqwest/Cargo.toml b/src/reqwest/Cargo.toml
index 876e34f8d5..c8a15e5054 100644
--- a/src/reqwest/Cargo.toml
+++ b/src/reqwest/Cargo.toml
@@ -1,12 +1,12 @@
 [package]
 name = "elastic_reqwest"
-version = "0.20.0"
+version = "0.20.1"
 authors = ["Ashley Mannix <ashleymannix@live.com.au>", "Stephan Buys <stephan.buys@gmail.com>"]
 license = "Apache-2.0"
 description = "A lightweight implementation of the Elasticsearch API based on reqwest."
 documentation = "https://docs.rs/elastic_reqwest/"
 repository = "https://github.com/elastic-rs/elastic"
-exclude = [ "samples" ]
+readme = "README.md"
 
 [dependencies]
 serde = "~1"
diff --git a/src/responses/Cargo.toml b/src/responses/Cargo.toml
index 81b6a74956..912e5ba57a 100644
--- a/src/responses/Cargo.toml
+++ b/src/responses/Cargo.toml
@@ -1,11 +1,12 @@
 [package]
 authors = ["Stephan Buys <stephan.buys@panoptix.co.za>", "Ashley Mannix <ashleymannix@live.com.au>"]
 name = "elastic_responses"
-version = "0.20.0"
+version = "0.20.1"
 license = "MIT/Apache-2.0"
 description = "Parses search results from Elasticsearch and presents results using convenient iterators."
 documentation = "https://docs.rs/elastic_responses"
 repository = "https://github.com/elastic-rs/elastic"
+readme = "README.md"
 
 [dependencies]
 log = "~0.3"
diff --git a/src/types/Cargo.toml b/src/types/Cargo.toml
index d0a0517fe3..a87d23e6f1 100644
--- a/src/types/Cargo.toml
+++ b/src/types/Cargo.toml
@@ -1,11 +1,12 @@
 [package]
 name = "elastic_types"
-version = "0.20.0"
+version = "0.20.1"
 authors = ["Ashley Mannix <ashleymannix@live.com.au>"]
 license = "Apache-2.0"
 description = "A strongly-typed implementation of Elasticsearch core types and Mapping API."
 documentation = "https://docs.rs/elastic_types/"
 repository = "https://github.com/elastic-rs/elastic"
+readme = "README.md"
 
 [dependencies]
 serde = "~1"
diff --git a/src/types_derive/Cargo.toml b/src/types_derive/Cargo.toml
index 6aaeb32433..d9d5e40cf5 100644
--- a/src/types_derive/Cargo.toml
+++ b/src/types_derive/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "elastic_types_derive"
-version = "0.20.0"
+version = "0.20.1"
 authors = ["Ashley Mannix <ashleymannix@live.com.au>"]
 license = "Apache-2.0"
 description = "Compile-time code generation for Elasticsearch type implementations."
diff --git a/src/types_derive_internals/Cargo.toml b/src/types_derive_internals/Cargo.toml
index 0f22441334..aa994c57d4 100644
--- a/src/types_derive_internals/Cargo.toml
+++ b/src/types_derive_internals/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "elastic_types_derive_internals"
-version = "0.20.0"
+version = "0.20.1"
 authors = ["Ashley Mannix <ashleymannix@live.com.au>"]
 license = "Apache-2.0"
 description = "Codegen internals for elastic_types."


Test patch: