docs: improve readme

LICENSE

@@ -1,6 +1,6 @@
 ISC License
 
-Copyright (c) 2021
+Copyright (c) 2021 Baptiste Girardeau
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above
@@ -12,4 +12,4 @@ AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
 INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-PERFORMANCE OF THIS SOFTWARE.
+PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -4,49 +4,56 @@
 [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
 [![CI](https://github.com/baptiste0928/cargo-install/actions/workflows/ci.yml/badge.svg)](https://github.com/baptiste0928/cargo-install/actions/workflows/ci.yml)
 
-GitHub action for cache-efficient Rust crates installation.
+This action enables you to run `cargo install` in your GitHub workflows,
+and automatically caches the resulting binaries to speed up subsequent builds.
+
+> ✨ **Update:** The recent v2 update introduces some breaking changes. Read
+> the [changelog] before updating.
 
 ## Features
-- Install any crate published on [crates.io].
-- Crates are compiled only if no previous cached version is found.
-- Always update to the latest version, respecting the provided version range.
-- Tested and working on Linux, Windows and MacOS runners.
+- Install any Rust binary crate published on [crates.io].
+- Automatically cache installed binaries to avoid compiling them each run.
+- Keep crates updated, with an optional version range to avoid breakages.
+- Works on Linux, Windows and MacOS runners.
 
 ## Usage
-The following example workflow install the [`cargo-hakari`] crate. Read
+The following example steps install the [`cargo-hack`] crate. Read
 [Quickstart for GitHub Actions] to learn more about Actions usage.
 
 ```yaml
-- name: Install cargo-hakari
-  uses: baptiste0928/cargo-install@v1
+- name: Install cargo-hack
+  uses: baptiste0928/cargo-install@v2
   with:
-    crate: cargo-hakari
-    version: "0.9"  # Most recent version compatible with 0.9
+    crate: cargo-hack
+    version: "^0.5"  # You can specify any semver range
 
-- name: Run cargo-hakari
-  run: cargo hakari generate --diff  # Installed crate has been added to PATH
+- name: Run cargo hack
+  run: cargo hack --version
 ```
 
+If no version is specified, the latest version will be installed. The
+`--locked` flag is added by default to avoid breakages due to unexpected
+dependencies updates.
+
 ### Inputs
 - `crate` *(required)*: Name of the crate to install.
-- `version`: Compatible version ranges (defaults to latest version). If no
-operator is provided, it is interpreted like a caret (`^`) operator. The latest
-semver compatible version will be installed.
+- `version`: Version to install (defaults to the latest version). Supports any
+  semver range.
 - `features`: Space or comma-separated list of crate features to enable.
-- `locked`: Use the crate `Cargo.lock` if available. This adds `--locked` to
-the install command arguments.
-- `args`: Additional args to pass to `cargo install`.
-- `cache-key`: Additional key added to the automatic cache key used to manually
-invalidate the cache.
+- `locked`: Use the crate `Cargo.lock` if available (enabled by default).
+  This adds `--locked` to the install command arguments.
+- `args`: Additional arguments to pass to `cargo install`.
+- `cache-key`: Additional string added to the cache key used to manually
+  invalidate the cache.
 
 ### Outputs
 - `version`: The version of the crate that has been installed.
 - `cache-hit`: A boolean indicating whether the crate was restored from cache.
 
 ## Caching
 Compiled binaries of installed crates are automatically cached. If a cached
-version is present when the action is executed, it will be used. This allows the
-installation of the crate to be almost instant in most cases.
+version is present when the action is executed, it will be used. This allows
+the installation of the crate to be almost instant in most cases.
 
 Cached binaries will be automatically removed by GitHub if they have not been
 accessed in the last 7 days. Read [Caching dependencies to speed up workflows]
@@ -55,43 +62,30 @@ to learn more about caching with GitHub Actions.
 <details>
   <summary><strong>Cache key details</strong></summary>
 
-  The `~/.cargo-install/<crate-name>` folder is cached with the `cargo-install-<hash>`
-  key. The cache key is composed of the following elements:
+  The `~/.cargo-install/<crate-name>` folder is cached with a cache key that
+  follows the following pattern:
 
-  - The crate name.
-  - The exact installed crate version (not the `version` input).
-  - The action `job` and runner os name.
-  - List of installed features.
-  - If provided, the `cache-key` input value.
-
-  These values are hashed and a 20 characters hex digest is used as the cache key.
+  ```
+  cargo-install-<crate>-<version>-<hash>
+  ```
 
+  The hash is derived from the action job and runner os name and the
+  installation arguments. The `cache-key` value is added to the hashed string
+  if provided.
 </details>
 
-### Custom cache key
-If needed, you can specify an additional key that will be added to the automatic
-cache key with the `cache-key` input. This can be useful to manually invalidate
-the cache.
-
-```yaml
-- name: Install cargo-hakari
-  uses: baptiste0928/cargo-install@v1
-  with:
-    crate: cargo-hakari
-    cache-key: customKey  # Custom key added to the automatic cache key
-```
-
 ## Security
 Crates are installed using `cargo install` and the latest version is retrieved
-with the [crates.io] API. If you want harder security, you can specify a strict
-version requirement (e.g. `=0.9.1`) and manually bump the version on crate updates.
+with the [crates.io] API. You can ask to install a specific version by not
+using any semver range operator.
 
 ## Contributing
 There is no particular contribution guidelines, feel free to open a new PR to
-improve the code. If you want to introduce a new feature, please create an issue
-before.
+improve the code. If you want to introduce a new feature, please create an
+issue before.
 
+[changelog]: https://github.com/baptiste0928/cargo-install/blob/next/CHANGELOG.md
 [crates.io]: https://crates.io
-[`cargo-hakari`]: https://crates.io/crates/cargo-hakari
+[`cargo-hack`]: https://crates.io/crates/cargo-hack
 [Quickstart for GitHub Actions]: https://docs.github.com/en/actions/quickstart
 [Caching dependencies to speed up workflows]: https://docs.github.com/en/actions/advanced-guides/caching-dependencies-to-speed-up-workflows