Update README with feature flags examples #458
Conversation
README.md
Outdated
| ``` | ||
| --default-features | ||
| Use only the crate-defined default features, as well as any features added explicitly via other flags. | ||
|
|
||
| Using this flag disables the heuristic that enables all features except `unstable`, `nightly`, `bench`, `no_std`, and ones starting with `__`. | ||
|
|
||
| --only-explicit-features | ||
| Use no features except ones explicitly added by other flags. | ||
|
|
||
| Using this flag disables the heuristic that enables all features except `unstable`, `nightly`, `bench`, `no_std`, and ones starting with `__`. | ||
|
|
||
| --features <NAME> | ||
| Add a feature to the set of features being checked. The feature will be used in both the baseline and the current version of the crate | ||
|
|
||
| --baseline-features <NAME> | ||
| Add a feature to the set of features being checked. The feature will be used in the baseline version of the crate only | ||
|
|
||
| --current-features <NAME> | ||
| Add a feature to the set of features being checked. The feature will be used in the current version of the crate only | ||
|
|
||
| --all-features | ||
| Use all the features, including features named `unstable`, `nightly`, `bench`, `no_std` or starting with `__`, that are otherwise disabled by default | ||
| ``` |
There was a problem hiding this comment.
This code block doesn't look good when rendered:
https://github.com/staniewzki/cargo-semver-check/tree/cli-specify-features#what-features-does-cargo-semver-checks-enable-in-the-tested-crates
There was a problem hiding this comment.
Yes, it is little bit awkward. Some solutions I see:
- Try to wrap the lines to make them shorter. This still results in a big code block.
- Move it out of a codeblock, and briefly explain all the flags related to features.
- Scrap it altogether, and explain the functionality in a shorter way.
There was a problem hiding this comment.
I implemented the 2. solution, and I think I like it.
|
@staniewzki do you think you'd be able to wrap this up in the next couple of days? If not, just let me know and I can take it over. Rust 1.70 comes out tomorrow and it's a good time to ship our own new release with explicit 1.70 support and dropping 1.65/1.66. It would be great to have the docs up in time for the new version so they sync to crates.io. |
Yes, I hope to finish this up quickly! I've already started working on your comments. |
staniewzki
force-pushed
the
cli-specify-features
branch
from
275bec8 to
354d578
Compare
|
I have notices that in #463 the help messages were not updated, so I am adding that here. |
README.md
Outdated
| | none | `std`, `alloc`, `derive`, `rc` | | ||
| | `--features unstable` | `std`, `alloc`, `derive`, `rc`, `unstable` | | ||
| | `--all-features` | `std`, `alloc`, `derive`, `rc`, `unstable` | | ||
| | `--default-features` | `std` | | ||
| | `--default-features --features derive` | `std`, `derive` | | ||
| | `--only-explicit-features --features unstable` | `unstable` | |
There was a problem hiding this comment.
This is much clearer already.
Have you thought about possibly adding an "explanation" column to the right?
For example:
- In the
nonerow it could say: "Featureunstableis excluded by the default heuristic." - In the next row it could say: "The flag explicitly adds
unstableto the heuristic's selections."
etc.
There was a problem hiding this comment.
I think this is a good idea, unfortunately now there are line breaks in the flags, but I don't think that is a big issue.
There was a problem hiding this comment.
yeah, it's unfortunate but definitely the lesser problem, this is fine as-is
Co-authored-by: Predrag Gruevski <2348618+obi1kenobi@users.noreply.github.com>
|
Nicely done! I'm going to prep a release shortly. |
I am not sure if adding this to FAQ is the best approach, especially as this section is pretty big relative to the others.
There's also a slight change in a comment that I didn't commit in the last PR on accident.