Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit c6206d3

Browse files
authoredJan 16, 2024
New Logo (#628)
* update readme * add brand assets * Visual Design rename
1 parent 15426b7 commit c6206d3

20 files changed

+2172
-18
lines changed
 

‎README.md

+34-18
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
<p align="center">
2+
<img alt="semver-checks" src="./brand/banner.png" width="800" />
3+
</p>
4+
15
# cargo-semver-checks
26

37
Lint your crate API changes for semver violations.
@@ -16,6 +20,7 @@ $ cargo semver-checks
1620
```
1721

1822
Or use as a [GitHub Action](https://github.com/obi1kenobi/cargo-semver-checks-action) (used in .github/workflows/ci.yml in this repo):
23+
1924
```yaml
2025
- name: Check semver
2126
uses: obi1kenobi/cargo-semver-checks-action@v2
@@ -95,6 +100,7 @@ No, it does not have to be published anywhere. You'll just need to use a flag to
95100
By default, `cargo-semver-checks` uses crates.io to look up the previous version of the crate,
96101
which is used as the baseline for semver-checking the current version of the crate.
97102
The following flags can be used to explicitly specify a baseline instead:
103+
98104
```
99105
--baseline-version <X.Y.Z>
100106
Version from registry to lookup for a baseline
@@ -118,26 +124,28 @@ registries other than crates.io should use one of the other approaches of genera
118124
By default, checking is done on all features except features named `unstable`, `nightly`, `bench`, `no_std`, or ones with prefix `_`, `unstable-`, or `unstable_`, as such names are commonly used for private or unstable features.
119125

120126
This behaviour can be overriden. Checked feature set can be changed to:
121-
- *all* the features, selected with `--all-features`,
127+
128+
- _all_ the features, selected with `--all-features`,
122129
- only the crate's default features, selected with `--default-features`,
123130
- empty set, selected with `--only-explicit-features`.
124131

125132
Additionally, features can be enabled one-by-one, using flags `--features`, `--baseline-features` and `--current-features`.
126133

127134
For example, consider crate [serde](https://github.com/serde-rs/serde), with the following features (per v1.0.163):
135+
128136
- `std` - the crate's only default feature,
129137
- `alloc`, `derive`, `rc` - optional features,
130138
- `unstable` - a feature that possibly breaks semver.
131139

132-
| used flags | selected feature set | explanation |
133-
|--|--|--|
134-
| none | `std`, `alloc`, `derive`, `rc` | Feature `unstable` is excluded by the default heuristic. |
135-
| `--features unstable` | `std`, `alloc`, `derive`, `rc`, `unstable` | The flag explicitly adds `unstable` to the heuristic's selections. |
136-
| `--all-features` | `std`, `alloc`, `derive`, `rc`, `unstable` | All the features are used, disabling the default heuristic. |
137-
| `--default-features` | `std` | The crate has only one default feature. |
138-
| `--default-features --features derive` | `std`, `derive` | Feature `derive` is used along with crate's default features.
139-
| `--only-explicit-features` | none | No explicit features are passed. |
140-
| `--only-explicit-features --features unstable` | `unstable` | All features can be added explicitly, regardless of their name. |
140+
| used flags | selected feature set | explanation |
141+
| ---------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------ |
142+
| none | `std`, `alloc`, `derive`, `rc` | Feature `unstable` is excluded by the default heuristic. |
143+
| `--features unstable` | `std`, `alloc`, `derive`, `rc`, `unstable` | The flag explicitly adds `unstable` to the heuristic's selections. |
144+
| `--all-features` | `std`, `alloc`, `derive`, `rc`, `unstable` | All the features are used, disabling the default heuristic. |
145+
| `--default-features` | `std` | The crate has only one default feature. |
146+
| `--default-features --features derive` | `std`, `derive` | Feature `derive` is used along with crate's default features. |
147+
| `--only-explicit-features` | none | No explicit features are passed. |
148+
| `--only-explicit-features --features unstable` | `unstable` | All features can be added explicitly, regardless of their name. |
141149

142150
### Does `cargo-semver-checks` have false positives?
143151

@@ -167,6 +175,7 @@ if you'd like to contribute new lints!
167175
Append `--verbose` when semver-checking your crate to see the full list of performed semver checks.
168176

169177
Here are some example areas where `cargo-semver-checks` currently will not catch semver violations:
178+
170179
- breaking type changes, for example in the type of a field or function parameter
171180
- breaking changes in generics or lifetimes
172181
- breaking changes that exist when only a subset of all crate features are activated
@@ -191,8 +200,8 @@ it is announced in the release notes.
191200
### How is `cargo-semver-checks` similar to and different from other tools?
192201

193202
[rust semverver](https://github.com/rust-lang/rust-semverver) builds on top of
194-
rustc internals to build rlib's and compare their metadata. This strips the
195-
code down to the basics for identifying changes. However, is tightly coupled
203+
rustc internals to build rlib's and compare their metadata. This strips the
204+
code down to the basics for identifying changes. However, is tightly coupled
196205
to specific nightly compiler versions and [takes work to stay in
197206
sync](https://github.com/rust-lang/rust-semverver/search?q=Rustup+to&type=commits).
198207
As of April 17, 2023, it appears to be
@@ -206,11 +215,11 @@ This is limited to the feature and target the crate was compiled for.
206215
As of November 22, 2022, it appears to be
207216
[archived and no longer maintained](https://github.com/iomentum/cargo-breaking).
208217

209-
`cargo-semver-checks` sources its data from rustdoc's json output. While the
218+
`cargo-semver-checks` sources its data from rustdoc's json output. While the
210219
json output format is unstable, the rate of change is fairly low, reducing the
211-
churn in keeping up. The lints are also written as queries for `trustfall`
220+
churn in keeping up. The lints are also written as queries for `trustfall`
212221
["query everything" engine](https://github.com/obi1kenobi/trustfall), reducing
213-
the work for creating and maintaining them. Because of the extra data that
222+
the work for creating and maintaining them. Because of the extra data that
214223
rustdoc includes, some level of feature/target awareness might be able to be
215224
introduced.
216225

@@ -236,13 +245,14 @@ are intentionally yanked. Please use the `cargo-semver-checks` crate instead.
236245

237246
### What is the MSRV policy with respect to semver?
238247

239-
MSRV bumps are *not* considered major changes.
248+
MSRV bumps are _not_ considered major changes.
240249

241250
`cargo-semver-checks` has two Rust version bounds, since it depends on Rust
242251
both at compile-time and at runtime:
243-
- The MSRV for *compiling* `cargo-semver-checks` (_"compile MSRV"_) is currently Rust 1.70.
252+
253+
- The MSRV for _compiling_ `cargo-semver-checks` (_"compile MSRV"_) is currently Rust 1.70.
244254
This is primarily determined by our dependencies' MSRVs.
245-
- The MSRV for *checking crates* (_"runtime MSRV"_) is currently Rust 1.71.
255+
- The MSRV for _checking crates_ (_"runtime MSRV"_) is currently Rust 1.71.
246256
This is determined based on the rustdoc JSON format versions and
247257
known bugs in older rustdoc versions.
248258

@@ -253,6 +263,12 @@ Changes to the _compile MSRV_ may happen in any kind of version bump.
253263
As much as practically possible, we'll aim to make them
254264
simultaneously with _runtime MSRV_ bumps.
255265

266+
### Visual Design
267+
268+
Logo by [NUMI](https://github.com/numi-hq/open-design):
269+
270+
[<img src="https://raw.githubusercontent.com/numi-hq/open-design/main/assets/numi-lockup.png" alt="NUMI Logo" style="width: 200px;"/>](https://numi.tech/?ref=semver-checks)
271+
256272
### License
257273

258274
Available under the Apache License (Version 2.0) or the MIT license, at your option.
There was a problem loading the remainder of the diff.

0 commit comments

Comments
 (0)
Please sign in to comment.