Merge pull request #14 from BD103/1595-changes

bevyengine#1595 changes and touch-ups

content/contributing/helping-out/creating-examples.md

@@ -18,7 +18,7 @@ Examples in Bevy should be:
 When you add a new example, be sure to update `examples/README.md` with the new example and add it to the root `Cargo.toml` file.
 Run `cargo run -p build-templated-pages -- build-example-page` to do this automatically.
 Use a generous sprinkling of keywords in your description: these are commonly used to search for a specific example.
-See the [example style guide](.github/contributing/example_style_guide.md) to help make sure the style of your example matches what we're already using.
+See the [example style guide](#style-guide) to help make sure the style of your example matches what we're already using.
 
 More complex demonstrations of functionality are also welcome, but these should be submitted to [bevy-assets](https://github.com/bevyengine/bevy-assets).
 
@@ -30,13 +30,13 @@ Please adhere to the following guidelines when creating or updating an example.
 
 1. Examples should live in an appropriate subfolder of `/examples`.
 2. Examples should be a single file if possible.
-3. Assets live in `./assets`. Try to avoid adding new assets unless strictly necessary to keep the repo small. Don't add "large" asset files.
+3. Assets live in `/assets`. Try to avoid adding new assets unless strictly necessary to keep the repo small. Don't add "large" asset files.
 4. Each example should try to follow this order:
    1. Imports
    2. A `fn main()` block
    3. Example logic
 5. Try to structure app / plugin construction in the same fashion as the actual code.
-6. Examples should typically not have tests, as they are not directly reusable by the Bevy user.
+6. Examples should typically not have tests, as those are not directly reusable by the Bevy user.
 
 ### Stylistic preferences
 
@@ -68,7 +68,7 @@ Please adhere to the following guidelines when creating or updating an example.
 
 These examples demonstrate the usage of specific engine features in clear, minimal ways.
 
-1. Focus on demonstrating exactly one feature in an example
+1. Focus on demonstrating exactly one feature in an example.
 2. Try to keep your names divorced from the context of a specific game, and focused on the feature you are demonstrating.
 3. Where they exist, show good alternative approaches to accomplish the same task and explain why you may prefer one over the other.
 4. Examples should have a visible effect when run, either in the command line or a graphical window.
@@ -77,7 +77,7 @@ These examples demonstrate the usage of specific engine features in clear, minim
 
 These examples show how to build simple games in Bevy in a cohesive way.
 
-1. Each of these examples lives in the [/examples/games] folder.
+1. Each of these examples lives in the `/examples/games` folder.
 2. Aim for minimum but viable status: the game should be playable and not obviously buggy but does not need to be polished, featureful, or terribly fun.
 3. Focus on code quality and demonstrating good, extensible patterns for users.
    1. Make good use of enums and states to organize your game logic.

content/contributing/helping-out/how-you-can-help.md

@@ -59,6 +59,8 @@ If you already know what you want to work on, all you have to do is make your ch
 
 {% callout() %}
 When working on the engine's code, it's a good idea to introduce yourself in the `#engine-dev` channel on [Discord] and tell people about your plans. Communicating your progress early and often can help you avoid avoid headaches and disagreements during code review.
+
+[Discord]: https://discord.gg/bevy
 {% end %}
 
 ## Writing docs and examples

content/contributing/helping-out/opening-pull-requests.md

@@ -10,20 +10,23 @@ weight = 3
 Most changes don't require much "process". If your change is relatively straightforward, just do the following:
 
 1. A community member (that's you!) creates one of the following:
-    * [GitHub Discussions](https://github.com/bevyengine/bevy/discussions): An informal discussion with the community. This is the place to start if you want to propose a feature or specific implementation.
+    * [GitHub Discussions]: An informal discussion with the community. This is the place to start if you want to propose a feature or specific implementation.
     * [Issue](https://github.com/bevyengine/bevy/issues): A formal way for us to track a bug or feature. Please look for duplicates before opening a new issue and consider starting with a Discussion.
     * [Pull Request](https://github.com/bevyengine/bevy/pulls) (or PR for short): A request to merge code changes. This starts our "review process". You are welcome to start with a pull request, but consider starting with an Issue or Discussion for larger changes (or if you aren't certain about a design). We don't want anyone to waste their time on code that didn't have a chance to be merged! But conversely, sometimes PRs are the most efficient way to propose a change. Use your own judgment here.
-2. Other community members review and comment in an ad-hoc fashion. Active subject matter experts may be pulled into a thread using `@mentions`. If your PR has been quiet for a while and is ready for review, feel free to leave a message to "bump" the thread, or bring it up on [Discord](https://discord.gg/bevy) in an appropriate engine development channel.
+2. Other community members review and comment in an ad-hoc fashion. Active subject matter experts may be pulled into a thread using `@mentions`. If your PR has been quiet for a while and is ready for review, feel free to leave a message to "bump" the thread, or bring it up on [Discord] in an appropriate engine development channel.
 3. Once they're content with the pull request (design, code quality, documentation, tests), individual reviewers leave "Approved" reviews.
 4. After consensus has been reached (typically two approvals from the community or one for extremely simple changes) and CI passes, the [S-Ready-For-Final-Review](https://github.com/bevyengine/bevy/issues?q=is%3Aopen+is%3Aissue+label%3AS-Ready-For-Final-Review) label is added.
 5. When they find time, someone with merge rights performs a final code review and queues the PR for merging.
 
+[Discord]: https://discord.com/invite/bevy
+[GitHub Discussions]: https://github.com/bevyengine/bevy/discussions
+
 ### Complex changes
 
 Individual contributors often lead major new features and reworks. However these changes require more design work and scrutiny. Complex changes like this tend to go through the following life-cycle:
 
 1. A need or opportunity is identified and an issue is made, laying out the general problem.
-2. As needed, this is discussed further on that issue thread, in cross-linked [GitHub Discussion] threads, or on [Discord] in the Engine Development channels.
+2. As needed, this is discussed further on that issue thread, in cross-linked [GitHub Discussions] threads, or on [Discord] in the Engine Development channels.
 3. Either a Draft Pull Request or an RFC is made. As discussed in the [RFC repo](https://github.com/bevyengine/rfcs), complex features need RFCs, but these can be submitted before or after prototyping work has been started.
 4. If feasible, parts that work on their own (even if they're only useful once the full complex change is merged) get split out into individual PRs to make them easier to review.
 5. The community as a whole helps improve the Draft PR and/or RFC, leaving comments, making suggestions, and submitting pull requests to the original branch.
@@ -44,8 +47,8 @@ If you're new to Bevy, here's the workflow we use:
     * `cargo run -p ci -- lints` - to run formatting and Clippy.
     * `cargo run -p ci -- test` - to run tests.
     * `cargo run -p ci -- doc` - to run doc tests and doc checks.
-    * `cargo run -p ci -- compile` - to check that everything that must compile still does (examples and benches), and that some that we want to be sure *don't* compile ([`crates/bevy_ecs_compile_fail_tests`](./crates/bevy_ecs_compile_fail_tests)).
-    * to get more information on commands available and what is run, check the [tools/ci crate](./tools/ci).
+    * `cargo run -p ci -- compile` - to check that everything that must compile still does (examples and benches), and that some that we want to be sure *don't* compile ([`crates/bevy_ecs/compile_fail`](https://github.com/bevyengine/bevy/tree/main/crates/bevy_ecs/compile_fail)).
+    * to get more information on commands available and what is run, check the [tools/ci crate](https://github.com/bevyengine/bevy/tree/main/tools/ci).
 4. When working with Markdown (`.md`) files, Bevy's CI will check markdown files (like this one) using [markdownlint](https://github.com/DavidAnson/markdownlint).
 To locally lint your files using the same workflow as our CI:
    1. Install [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli).
@@ -62,15 +65,15 @@ To locally lint your files using the same workflow as our CI:
 
 If you end up adding a new official Bevy crate to the `bevy` repo:
 
-1. Add the new crate to the [./tools/publish.sh](./tools/publish.sh) file.
-2. Check if a new cargo feature was added, update [cargo_features.md](https://github.com/bevyengine/bevy/blob/main/docs/cargo_features.md) as needed.
+1. Add the new crate to the [tools/publish.sh](https://github.com/bevyengine/bevy/blob/main/tools/publish.sh) file.
+2. Check if a new cargo feature was added, update [docs/cargo_features.md](https://github.com/bevyengine/bevy/blob/main/docs/cargo_features.md) as needed.
 
 When contributing, please:
 
 * Prefer small PRs that incrementally improve things.
 * Explain what you're doing and why.
 * Try to loosely follow the workflow in [*Making changes to Bevy*](#making-changes-to-bevy).
-* Consult the [style guide](.github/contributing/engine_style_guide.md) to help keep our code base tidy.
+* Consult the [style guide](@/contributing/helping-out/creating-examples.md#style-guide) to help keep our code base tidy.
 * Document new code with doc comments.
 * Include clear, simple tests.
 * Add or improve the examples when adding new user-facing functionality.
@@ -87,8 +90,6 @@ Once you have opened your PR, your next task will be to shepherd it through comm
 
 You may find that your reviewers sometimes misunderstand your work, ask for changes you disagree with, or request additional changes you aren't interested in making. If you find yourself disagreeing with a reviewer, it's fine to politely say "no" or indicate that their suggestion would be better left to a follow-up PR.
 
-[Discord]: https://discord.com/invite/bevy
-
 ## Adopting pull requests
 
 Occasionally authors of pull requests get busy or become unresponsive, or project members fail to reply in a timely manner.
@@ -103,6 +104,6 @@ This may sometimes even skip the labeling process since at that point the PR has
 With this label added, it's best practice to fork the original author's branch.
 This ensures that they still get credit for working on it and that the commit history is retained.
 When the new pull request is ready, it should reference the original PR in the description.
-Then notify org members to close the original.
+Then, notify org members to close the original.
 
 * For example, you can reference the original PR by adding the following to your PR description: `Adopted #number-original-pull-request`

content/contributing/helping-out/reviewing-pull-requests.md

@@ -13,7 +13,7 @@ Anyone!
 
 You don't need to be an Elder Rustacean to be useful here: anyone can catch missing tests, unclear docs, logic errors, and so on. If you have specific skills (e.g. advanced familiarity with unsafe code, rendering knowledge or web development experience) or personal experience with a problem, try to prioritize those areas to ensure we can get appropriate expertise where we need it.
 
-If you find (or make) a PR that you don't feel comfortable reviewing, but you can think of someone who does, consider using Github's "Request review" functionality (in the top-right of the PR screen) to bring the work to their attention. If they're not a Bevy Org member, you'll need to ping them in the thread directly: that's fine too! Almost everyone working on Bevy is a volunteer: this should be treated as a gentle nudge, rather than an assignment of work. Consider checking the Git history for appropriate reviewers, or ask on Discord for suggestions.
+If you find a PR that you don't feel comfortable reviewing, but you can think of someone who does, consider using Github's "Request review" functionality (in the top-right of the PR screen) to bring the work to their attention. If they're not a Bevy Org member, you'll need to ping them in the thread directly: that's fine too! Almost everyone working on Bevy is a volunteer: this should be treated as a gentle nudge, rather than an assignment of work. Consider checking the Git history for appropriate reviewers, or ask on Discord for suggestions.
 
 ## How to review a Pull Request
 
@@ -23,7 +23,7 @@ If you're new to GitHub, there's a lot of great information on the official [Pul
 
 Focus on giving constructive, actionable feedback that results in real improvements to code quality or end-user experience. If you don't understand why an approach was taken, please ask!
 
-Provide actual code suggestions when that is helpful. Small changes work well as comments or in-line suggestions on specific lines of codes. Larger changes deserve a comment in the main thread, or a pull request to the original author's branch (but please mention that you've made one). When in doubt about a matter of architectural philosophy, refer back to [What we're trying to build](../introduction.md) for guidance.
+Provide actual code suggestions when that is helpful. Small changes work well as comments or in-line suggestions on specific lines of codes. Larger changes deserve a comment in the main thread, or a pull request to the original author's branch (but please mention that you've made one). When in doubt about a matter of architectural philosophy, refer back to [What we're trying to build](@/contributing/introduction.md#what-we-re-trying-to-build) for guidance.
 
 It's okay to leave an approval even if you aren't 100% confident on all areas of the PR: just be sure to note your limitations. When maintainers are evaluating the PR to be merged, they'll make sure that there's good coverage on all of the critical areas. If you can only check that the math is correct, and another reviewer can check everything but the math, we're in good shape!
 

content/contributing/helping-out/writing-docs.md

@@ -35,9 +35,9 @@ To check out any local changes you've made:
 
 Your web browser should open and you should be able to access a local version of the `docs.rs` page from there.
 
-:::warning
+{% callout(type="warning") %}
 The code in doc comments is compiled and tested to ensure that the examples work for our readers.
-:::
+{% end %}
 
 Doc-tests run as part of the normal `cargo test` suite. To only run doc-tests, you can use `cargo test --doc`.
 
@@ -55,9 +55,9 @@ To check out any local changes you've made:
 
 A local server should start and you should be able to access a local version of the website from there.
 
-:::warning
+{% callout(type="warning") %}
 The code in the book is compiled and tested to make sure that the examples work for readers.
-:::
+{% end %}
 
 To check your local changes, move into the `code-validation` folder of this project using `cd code-validation`, and then run `cargo test`. If you write a new section of the book, you have to add it in `code-validation/src/lib.rs` to enable code validation for it.
 
@@ -78,12 +78,12 @@ These users tend to be driven by curiosity, or are aiming to carefully develop a
 Crucially, these paths are independent of the experience levels of the learner!
 Bevy intentionally aims to be inclusive of both complete beginners who have never programmed before, and professionals coming from other engines.
 
-|                      | **Beginner**                                                       | **Professional**                                                     |
-| -------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| **Example-first**    | Enthusiastic, wants to create a new version of the game they love. | Exploratory, wants to dive in and see how Bevy holds up in practice. |
-| **Definition-first** | Curious, wants to understand how making games works.               | Critical, wants to understand Bevy's unique design choices.          |
+| | **Beginner** | **Professional** |
+|-|-|-|
+| **Example-first** | Enthusiastic, wants to create a new version of the game they love. | Exploratory, wants to dive in and see how Bevy holds up in practice. |
+| **Definition-first** | Curious, wants to understand how making games works. | Critical, wants to understand Bevy's unique design choices. |
 
-Each of these requires their own complementary learning paths that branch as soon as they get to the [Learn page](https://bevyengine.org/learn/) to ensure that the first experience that they have with Bevy matches what they need.
+Each of these requires their own complementary learning paths that branch as soon as they get to the [Learn page](@/learn/_index.md) to ensure that the first experience that they have with Bevy matches what they need.
 
 Once users have completed the introductory learning materials in their path of choice, they can begin creating their own games or move on to our advanced examples to see how everything comes together in a realistic way.