Improve `README.md`, add `CONTRIBUTING.md`, and more! #152

BD103 · 2024-10-17T18:17:15Z

Closes #109.

This PR:

Creates bevy_lint's README.md
Modifies the main CLI's README.md
Creates and moves some information into CONTRIBUTING.md
Adds README.md into bevy_cli's rustdoc output.
Sets up some custom CSS styles so Github alerts render nicely in rustdoc.

Todo

Install bleeding edge from Git
~~Install from a release~~
- bevy_lint cannot 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.
Dealing with #![register_tool(bevy)], #[allow(bevy::lint)], and #[cfg_attr(bevy_lint, ...)].

BD103 · 2024-10-18T03:34:40Z

Unfortunately Github alerts are currently broken, but I'll take a look in the morning.

BD103 · 2024-10-18T12:43:17Z

So I tried using Github's alerts

Tip

like this

but they don't render correctly when wrappen in a <div>, turning into

[!CAUTION]

this :(

As such, I'm going to keep the pretty rustdoc alerts but replace Github's side

Note

With this. It's not nearly as nice, but I like it better than having no pretty alerts at all, or having rustdoc's plain block quotes.

Also fix links in `rustdoc`.

MrGVSV · 2024-10-19T19:31:15Z

bevy_lint/README.md

+
+at your option.
+
+## Contributing


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.

alice-i-cecile · 2024-10-19T21:50:39Z

README.md

@@ -2,10 +2,25 @@

 A Bevy CLI tool.


This needs more expansion to describe the current and planned features. This is the first thing people will read!

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!

alice-i-cecile · 2024-10-19T21:51:30Z

bevy_lint/README.md

+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 \


How do users check that this is still the right version?

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?

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

bevy_lint/README.md

alice-i-cecile · 2024-10-19T21:55:16Z

bevy_lint/README.md

+
+### 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:


This framing isn't clear to me. Start with a clear description of what the user is trying to do :)

alice-i-cecile · 2024-10-19T21:55:57Z

bevy_lint/README.md

+}
+```
+
+If you do not register `bevy` as a tool, `#[allow(bevy::lint_name)]` and related attributes will fail to compile.


This needs to be moved up: motivation first.

alice-i-cecile · 2024-10-19T21:56:44Z

bevy_lint/README.md

+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(...)]`:


Suggested change

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(...)]`:

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

bevy_lint/README.md

…ty table

…source of truth

BD103 · 2024-10-20T03:22:12Z

Thanks for the reviews! It clearly still needs a lot of work, so I'm going to pick this back up tomorrow. Cheers :)

…ock/bevy_cli into installation-and-usage

BD103 · 2024-10-21T12:09:41Z

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 #155, extracted from #152. While refactoring I moved `extract-rust-version` to a separate, callable workflow that can be used by both `ci.yml` and `docs.yml`.

Closes #156, originally part of #152. This adds a small contributing guide for the Bevy CLI, and updates the root `README.md` to include a list of features, various links, and licensing info.

Closes #158, extracted from #152, will be used in #109. This adds pretty alerts in `rustdoc` for `bevy_lint` that will be used in #109 when writing `bevy_lint`'s user documentation. <img width="908" alt="alerts in light mode" src="https://github.com/user-attachments/assets/4ee666f2-bb85-40de-b0f6-19b7a19a45e9"> <img width="908" alt="alerts in dark mode" src="https://github.com/user-attachments/assets/67ce7308-175c-4673-9c1e-7f89c59c4c73"> <img width="908" alt="alerts in dark mode, with the ayu theme" src="https://github.com/user-attachments/assets/e2de4717-bc63-4d1d-bb88-83714b3cf530">

Originally part of #152, closes #109. This fills out the `README.md` for `bevy_lint`, including installation intructions and a guide on usage. This is the [final blocker to release 0.1.0](https://github.com/TheBevyFlock/bevy_cli/milestone/1), which is exciting! I tried to split this up into small, incremental commits, so you may have an easier time [reviewing it like that](https://github.com/TheBevyFlock/bevy_cli/pull/170/commits). You can build the `rustdoc` version of the `README.md` by calling `cargo doc-lints`.

feat: create bevy_lint README.md

e91ef3c

BD103 added A-Linter Related to the linter and custom lints C-Docs An improvement in documentation labels Oct 17, 2024

BD103 added 9 commits October 17, 2024 21:09

Merge branch 'main' into installation-and-usage

e8c1d9f

fix: update README.md to new toolchain version

1dd27d2

feat: add more details about nightly rust and the linter in general

f4bbc1b

feat: create CONTRIBUTING.md and add license info to README.md

f3a4b01

feat: link code of conduct and contributing guide in CONTRIBUTING.md

aeb5a6e

feat: add note about unofficiallity

ac5db52

feat: add section on configuring lints

d06d480

feat: include README.md in rustdoc output

dccb5d6

feat: style alerts in rustdoc

2e0c81d

BD103 marked this pull request as ready for review October 18, 2024 03:29

BD103 changed the title ~~Create README.md for bevy_lint~~ Improve README.md, add CONTRIBUTING.md, and more! Oct 18, 2024

BD103 added 3 commits October 19, 2024 13:06

feat: compromise between github and rustdoc

5489833

Also fix links in `rustdoc`.

feat: more general improvements

ea828aa

feat: final few changes

cd29605

MrGVSV reviewed Oct 19, 2024

View reviewed changes

alice-i-cecile reviewed Oct 19, 2024

View reviewed changes

bevy_lint/README.md Outdated Show resolved Hide resolved

alice-i-cecile reviewed Oct 19, 2024

View reviewed changes

bevy_lint/README.md Outdated Show resolved Hide resolved

alice-i-cecile reviewed Oct 19, 2024

View reviewed changes

bevy_lint/README.md Show resolved Hide resolved

BD103 added 2 commits October 19, 2024 21:21

refactor: rename etc folder to assets for consistency

28c0212

feat: begin contributing docs

666d995

BD103 added 6 commits October 19, 2024 22:02

feat: publish bevy_lint docs to github pages

2373f67

feat: improve root README.md with features and other links

fc10f2f

feat: split rust language version and rustup toolchain in compatibili…

28f1a18

…ty table

fix: clarify "linking to rustc" and move to compatibility table as …

6a8eadd

…source of truth

fix: explain _why_ we need rustc crates

ea7d98d

feat: note that [workspace.lints] is unsupported

fc928d8

BD103 marked this pull request as draft October 20, 2024 03:21

BD103 added 4 commits October 19, 2024 23:22

Merge branch 'main' into installation-and-usage

fbaf9fd

Merge branch 'installation-and-usage' of https://github.com/TheBevyFl…

29f2e3e

…ock/bevy_cli into installation-and-usage

fix: make header capitalization consistent

f7697ce

feat: create setup page for contributing docs

73681ed

BD103 force-pushed the installation-and-usage branch from b8a2009 to 73681ed Compare October 20, 2024 15:17

feat: begin creating a lint

67ae1e1

BD103 closed this Oct 21, 2024

BD103 added a commit that referenced this pull request Oct 29, 2024

Publish bevy_lint docs to Github Pages (#160)

8a0e3bf

Closes #155, extracted from #152. While refactoring I moved `extract-rust-version` to a separate, callable workflow that can be used by both `ci.yml` and `docs.yml`.

BD103 deleted the installation-and-usage branch October 29, 2024 11:58

BD103 mentioned this pull request Nov 7, 2024

Add README.md for bevy_lint #170

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve `README.md`, add `CONTRIBUTING.md`, and more! #152

Improve `README.md`, add `CONTRIBUTING.md`, and more! #152

BD103 commented Oct 17, 2024 •

edited

Loading

BD103 commented Oct 18, 2024

BD103 commented Oct 18, 2024

MrGVSV Oct 19, 2024

alice-i-cecile Oct 19, 2024

BD103 Oct 20, 2024

alice-i-cecile Oct 19, 2024

BD103 Oct 20, 2024

alice-i-cecile Oct 20, 2024

alice-i-cecile Oct 19, 2024

alice-i-cecile Oct 19, 2024

alice-i-cecile Oct 19, 2024

BD103 Oct 20, 2024

BD103 commented Oct 20, 2024

BD103 commented Oct 21, 2024


		### 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:

	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(...)]`:

Improve README.md, add CONTRIBUTING.md, and more! #152

Improve README.md, add CONTRIBUTING.md, and more! #152

Conversation

BD103 commented Oct 17, 2024 • edited Loading

Todo

BD103 commented Oct 18, 2024

BD103 commented Oct 18, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BD103 commented Oct 20, 2024

BD103 commented Oct 21, 2024

Improve `README.md`, add `CONTRIBUTING.md`, and more! #152

Improve `README.md`, add `CONTRIBUTING.md`, and more! #152

BD103 commented Oct 17, 2024 •

edited

Loading