docs(Compatibility Policy): adds an official compatibility policy to

Closes #740

Author: kbknapp

.github/CONTRIBUTING.md

@@ -35,6 +35,7 @@ There are a few goals of `clap` that I'd like to maintain throughout contributio
 * Remain backwards compatible when possible
   - If backwards compatibility *must* be broken, use deprecation warnings if at all possible before removing legacy code
   - This does not apply for security concerns
+  - `clap` officially supports the current stable version of Rust, minus two releases (i.e. if 1.13.0 is current, `clap` must support 1.11.0 and beyond)
 * Parse arguments quickly
   - Parsing of arguments shouldn't slow down usage of the main program
   - This is also true of generating help and usage information (although *slightly* less stringent, as the program is about to exit)

README.md

@@ -33,6 +33,8 @@ Table of Contents
 * [How to Contribute](#how-to-contribute)
   * [Running the tests](#running-the-tests)
   * [Goals](#goals)
+  * [Compatibility Policy](#compatibility-policy)
+    * [Minimum Version of Rust](#minimum-version-of-rust)
 * [License](#license)
 * [Recent Breaking Changes](#recent-breaking-changes)
   * [Deprecations](#deprecations)
@@ -645,11 +647,11 @@ fn main() {
 
 ## Usage
 
-For full usage, add `clap` as a dependency in your `Cargo.toml` file to use from crates.io:
+For full usage, add `clap` as a dependency in your `Cargo.toml` (it is **highly** recommended to use the `~major.minor.patch` style versions in your `Cargo.toml`, for more information see [Compatibility Policy](#compatibility-policy)) to use from crates.io:
 
 ```toml
 [dependencies]
-clap = "2"
+clap = "~2.19.0"
 ```
 
 Or get the latest changes from the master branch at github:
@@ -677,15 +679,15 @@ To disable these, add this to your `Cargo.toml`:
 
 ```toml
 [dependencies.clap]
-version = "2"
+version = "~2.19.0"
 default-features = false
 ```
 
 You can also selectively enable only the features you'd like to include, by adding:
 
 ```toml
 [dependencies.clap]
-version = "2"
+version = "~2.19.0"
 default-features = false
 
 # Cherry-pick the features you'd like to use
@@ -754,6 +756,28 @@ There are a few goals of `clap` that I'd like to maintain throughout contributio
   - Once parsing is complete, the memory footprint of `clap` should be low since the  main program is the star of the show
 * `panic!` on *developer* error, exit gracefully on *end-user* error
 
+### Compatibility Policy
+
+Because `clap` takes SemVer and compatibility seriously, this is the official policy regarding breaking changes and previous versions of Rust.
+
+`clap` will pin the minimum required version of Rust to the CI builds. Bumping the minimum version of Rust is considered a minor breaking change, meaning *at a minimum* the minor version of `clap` will be bumped.
+
+In order to keep from being suprised of breaking changes, it is **highly** recommended to use the `~major.minor.patch` style in your `Cargo.toml`:
+
+```toml
+[dependencies]
+clap = "~2.19.0"
+```
+
+This will cause *only* the patch version to be updated upon a `cargo update` call, and therefore cannot break due to new features, or bumped minimum versions of Rust.
+
+#### Minimum Version of Rust
+
+`clap` will officially support current stable Rust, minus two releases, but may work with prior releases as well. For example, current stable Rust at the time of this writing is 1.13.0, meaning `clap` is garunteed to compile with 1.11.0 and beyond.
+At the 1.14.0 release, `clap` will be garunteed to compile with 2.12.0 and beyond, etc.
+
+Upon bumping the minimum version of Rust (assuming it's within the stable-2 range), it *must* be clearly annotated in the `CHANGELOG.md`
+
 ## License
 
 `clap` is licensed under the MIT license. Please read the [LICENSE-MIT](LICENSE-MIT) file in this repository for more information.