Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Add Troubleshooting section to README #842

Merged
merged 2 commits into from
Jul 30, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 23 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,23 @@ 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

```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
```

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
Expand Down Expand Up @@ -435,6 +440,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):
Expand Down
Loading