Skip to content

Commit

Permalink
docs(README.md): adds guidance on when to use ~ in version pinning, a…
Browse files Browse the repository at this point in the history
…nd clarifies breaking change policy

Closes #765
  • Loading branch information
kbknapp committed Dec 8, 2016
1 parent 949690e commit 591eaef
Showing 1 changed file with 17 additions and 15 deletions.
32 changes: 17 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -366,7 +366,7 @@ subcommands:

Since this feature requires additional dependencies that not everyone may want, it is *not* compiled in by default and we need to enable a feature flag in Cargo.toml:

Simply change your `clap = "~2.19.0"` to `clap = {version = "~2.19.0", features = ["yaml"]}`.
Simply change your `clap = "2.19"` to `clap = {version = "2.19", features = ["yaml"]}`.

At last we create our `main.rs` file just like we would have with the previous two examples:

Expand Down Expand Up @@ -481,21 +481,16 @@ fn main() {

## Usage

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:
For full usage, add `clap` as a dependency in your `Cargo.toml` () to use from crates.io:

```toml
[dependencies]
clap = "~2.19.0"
```

Or get the latest changes from the master branch at github:
(**note**: If you are concerned with supporting a minimum version of Rust that is *older* than the current stable Rust minus 2 stable releases, it's recommended to use the `~major.minor.patch` style versions in your `Cargo.toml` which will only update the patch version automatically. For more information see the [Compatibility Policy](#compatibility-policy))

```toml
[dependencies.clap]
git = "https://github.com/kbknapp/clap-rs.git"
```

Add `extern crate clap;` to your crate root.
Then add `extern crate clap;` to your crate root.

Define a list of valid arguments for your program (see the [documentation](https://docs.rs/clap/) or [examples/](examples) directory of this repo)

Expand All @@ -513,15 +508,15 @@ To disable these, add this to your `Cargo.toml`:

```toml
[dependencies.clap]
version = "~2.19.0"
version = "2.19"
default-features = false
```

You can also selectively enable only the features you'd like to include, by adding:

```toml
[dependencies.clap]
version = "~2.19.0"
version = "2.19"
default-features = false

# Cherry-pick the features you'd like to use
Expand Down Expand Up @@ -639,11 +634,11 @@ There are a few goals of `clap` that I'd like to maintain throughout contributio

### Compatibility Policy

Because `clap` takes SemVer and compatibility seriously, this is the official policy regarding breaking changes and previous versions of Rust.
Because `clap` takes SemVer and compatibility seriously, this is the official policy regarding breaking changes and minimum required 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`:
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` only if you wish to target a version of Rust that is *older* than current stable minus two releases:

```toml
[dependencies]
Expand All @@ -659,6 +654,14 @@ At the 1.14.0 release, `clap` will be garunteed to compile with 1.12.0 and beyon

Upon bumping the minimum version of Rust (assuming it's within the stable-2 range), it *must* be clearly annotated in the `CHANGELOG.md`

#### Breaking Changes

`clap` takes a similar policy to Rust and will bump the major veresion number upon breaking changes with only the following exceptions:

* The breaking change is to fix a security concern
* The breaking change is to be fixing a bug (i.e. relying on a bug as a feature)
* The breaking change is a feature isn't used in the wild, or all users of said feature have given approval *prior* to the change

## License

`clap` is licensed under the MIT license. Please read the [LICENSE-MIT](LICENSE-MIT) file in this repository for more information.
Expand Down Expand Up @@ -706,12 +709,11 @@ As of 2.0.0 (From 1.x)
* **There is now a priority of order to determine the name** - This is perhaps the biggest breaking change. See the documentation for full details. Prior to this change, the value name took precedence. **Ensure your args are using the proper names (i.e. typically the long or short and NOT the value name) throughout the code**
* `ArgMatches::values_of` returns an `Values` now which implements `Iterator` (should not break any code)
* `crate_version!` returns `&'static str` instead of `String`
* Using the `clap_app!` macro requires compiling with the `unstable` feature because the syntax could change slightly in the future

### Deprecations

Old method names will be left around for several minor version bumps, or one major version bump.

As of 2.2.0:
As of 2.19.0:

* None!

0 comments on commit 591eaef

Please sign in to comment.