Improve README.md, add CONTRIBUTING.md, and more!
#152
Conversation
BD103
added
A-Linter
|
Unfortunately Github alerts are currently broken, but I'll take a look in the morning. |
BD103
changed the title
README.md for bevy_lintREADME.md, add CONTRIBUTING.md, and more!
|
So I tried using Github's alerts Tip like this but they don't render correctly when wrappen in a
As such, I'm going to keep the pretty
|
Also fix links in `rustdoc`.
|
|
||
| at your option. | ||
|
|
||
| ## Contributing |
There was a problem hiding this comment.
Can we include some more help for contributors here? At the very least, I think it would be helpful to explain how to run the UI tests.
README.md
Outdated
| @@ -2,10 +2,25 @@ | |||
|
|
|||
| A Bevy CLI tool. | |||
There was a problem hiding this comment.
This needs more expansion to describe the current and planned features. This is the first thing people will read!
There was a problem hiding this comment.
I wasn't sure about what other planned features we have, so I just rewrote the opening description and added a list of current features. Tell me if there's anything I missed in fc10f2f!
bevy_lint/README.md
Outdated
| First, you must install the toolchain and components described by [`rust-toolchain.toml`](https://github.com/TheBevyFlock/bevy_cli/blob/main/rust-toolchain.toml) using [Rustup]. As of the time of writing (October 17th, 2024), the command may look like this: | ||
|
|
||
| ```bash | ||
| $ rustup toolchain install nightly-2024-10-03 \ |
There was a problem hiding this comment.
How do users check that this is still the right version?
There was a problem hiding this comment.
The version is specified in rust-toolchain.toml. A user would replace nightly-2024-10-03 with the value in the channel = "..." field.
This is a bit rough, I'll admit. How can I rephrase this to be more clear?
There was a problem hiding this comment.
I think I would do:
First, you must install the exact toolchain expected by the version of the tool that you're using. You can determine the correct version by checking [rust-toolchain.toml]. For example, if you were using the commit HASH, you should look at...
|
|
||
| ### Configuring Lints | ||
|
|
||
| Toggling lints and lint groups requires the nightly `register_tool` feature. Even if your project uses stable Rust, you can still use this feature by detecting the `--cfg bevy_lint` flag: |
There was a problem hiding this comment.
This framing isn't clear to me. Start with a clear description of what the user is trying to do :)
| } | ||
| ``` | ||
|
|
||
| If you do not register `bevy` as a tool, `#[allow(bevy::lint_name)]` and related attributes will fail to compile. |
There was a problem hiding this comment.
This needs to be moved up: motivation first.
| unexpected_cfgs = { level = "warn", check-cfg = ["cfg(bevy_lint)"] } | ||
| ``` | ||
|
|
||
| You can now toggle lints and lint groups throughout the crate, as long as they are also behind `#[cfg_attr(...)]`: |
There was a problem hiding this comment.
| You can now toggle lints and lint groups throughout the crate, as long as they are also behind `#[cfg_attr(...)]`: | |
| You can now toggle lints and lint groups throughout your project, as long as they are also behind `#[cfg_attr(...)]`: |
There was a problem hiding this comment.
I worry about saying this because you need to call #![register_tool(bevy)] for each crate root that you use the bevy tool namespace. This means all libraries, binaries, examples, and integration tests. Let me try thinking of a better way to communicate this...
|
Thanks for the reviews! It clearly still needs a lot of work, so I'm going to pick this back up tomorrow. Cheers :) |
BD103
force-pushed
the
installation-and-usage
branch
from
b8a2009
to
73681ed
Compare
|
I'm going to split this up into a series of smaller PRs. It's too big already for my tastes, and some parts can get merged already while others need more work. |
Closes #109.
This PR:
bevy_lint'sREADME.mdREADME.mdCONTRIBUTING.mdREADME.mdintobevy_cli'srustdocoutput.rustdoc.Todo
Install from a releasebevy_lintcannot be published due to Git dependency #150 needs to be resolved before I can write this section. Also see conversation on Discord for more context.#![register_tool(bevy)],#[allow(bevy::lint)], and#[cfg_attr(bevy_lint, ...)].