From 9b3c14afb426dac164d5048c9d3f95ec6dc4fa11 Mon Sep 17 00:00:00 2001
From: Predrag Gruevski <2348618+obi1kenobi@users.noreply.github.com>
Date: Tue, 30 Jul 2024 14:37:50 -0400
Subject: [PATCH 1/2] Add Troubleshooting section to README

Resolves #841.
---
 README.md | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7acea5d2..425c04d9 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,7 @@ Lint your crate API changes for semver violations.
 - [Quick Start](#quick-start)
 - [FAQ](#faq)
 - [Configuration](#configuration)
+- [Troubleshooting](#troubleshooting)
 - [Contributing](https://github.com/obi1kenobi/cargo-semver-checks/blob/main/CONTRIBUTING.md)
 
 ## Quick Start
@@ -20,13 +21,19 @@ $ cargo install cargo-semver-checks --locked
 $ cargo semver-checks
 ```
 
-Or use as a [GitHub Action](https://github.com/obi1kenobi/cargo-semver-checks-action) (used in .github/workflows/ci.yml in this repo):
+Or use as a [GitHub Action](https://github.com/obi1kenobi/cargo-semver-checks-action) (used in `.github/workflows/ci.yml` in this repo):
 
 ```yaml
 - name: Check semver
   uses: obi1kenobi/cargo-semver-checks-action@v2
 ```
 
+Or if you use [`cargo-binstall`](https://github.com/cargo-bins/cargo-binstall), which will download prebuilt binaries instead of compiling from scratch:
+
+```sh
+$ cargo binstall cargo-semver-checks
+```
+
 ![image](https://user-images.githubusercontent.com/2348618/180127698-240e4bed-5581-4cbd-9f47-038affbc4a3e.png)
 
 Each failing check references specific items in the
@@ -435,6 +442,22 @@ When the `--manifest-path` option is used to specify the subject package's `Carg
 
 If `cargo-semver-checks` is executed in a way that skips reading the current manifest (such as with the `--current-rustdoc` flag), it is currently not possible to configure lints. Interest in, and progress toward resolving this limitation is tracked in [this issue](https://github.com/obi1kenobi/cargo-semver-checks/issues/827).
 
+## Troubleshooting
+
+This section documents common issues and the best ways to resolve them.
+
+### Running `cargo install cargo-semver-checks --locked` produces an error
+
+**Recommendation**: use [`cargo-binstall`](https://github.com/cargo-bins/cargo-binstall) to download a prebuilt binary if one is available for your platform, rather than compiling from scratch.
+
+Specific errors and their resolutions:
+- ["error: failed to run custom build command for `libz-ng-sys vX.Y.Z`"](https://github.com/obi1kenobi/cargo-semver-checks/issues/841)
+  - **Preferred resolution**: use a prebuilt binary to avoid this problem entirely.
+  - This error is caused by missing `cmake` on your system, which is required by a transitive dependency of `cargo-semver-checks`. `cargo` does not currently offer a mechanism for such a binary dependency to be declared as required, nor automatically installed when needed.
+  - You can usually install it via a command like `apt install cmake` or `brew install cmake`, depending on your platform.
+
+***
+
 ### Visual Design
 
 Logo by [NUMI](https://github.com/numi-hq/open-design):

From 654be3d3d13bd502d57e93128516299f3ac5ddaf Mon Sep 17 00:00:00 2001
From: Predrag Gruevski <2348618+obi1kenobi@users.noreply.github.com>
Date: Tue, 30 Jul 2024 14:41:28 -0400
Subject: [PATCH 2/2] Update README.md

---
 README.md | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 425c04d9..52ea3e22 100644
--- a/README.md
+++ b/README.md
@@ -15,9 +15,13 @@ Lint your crate API changes for semver violations.
 ## Quick Start
 
 ```sh
+# If you already use `cargo-binstall` for faster tool installations:
+$ cargo binstall cargo-semver-checks
+
+# Otherwise:
 $ cargo install cargo-semver-checks --locked
 
-# Check whether it's safe to release the new version:
+# Lint a new release for SemVer breakage before `cargo publish`:
 $ cargo semver-checks
 ```
 
@@ -28,12 +32,6 @@ Or use as a [GitHub Action](https://github.com/obi1kenobi/cargo-semver-checks-ac
   uses: obi1kenobi/cargo-semver-checks-action@v2
 ```
 
-Or if you use [`cargo-binstall`](https://github.com/cargo-bins/cargo-binstall), which will download prebuilt binaries instead of compiling from scratch:
-
-```sh
-$ cargo binstall cargo-semver-checks
-```
-
 ![image](https://user-images.githubusercontent.com/2348618/180127698-240e4bed-5581-4cbd-9f47-038affbc4a3e.png)
 
 Each failing check references specific items in the