Welcome chapter #176
Welcome chapter #176
Conversation
There was a problem hiding this comment.
Round two 😝. Good job, as always.
The structure of the chapter looks good to me, especially since the addition of the App section.
The level of communication could be improved though. In many points the book explains the details of the engine, while the Diátaxis Framework states:
[Explanation is] not a close-up view of the machinery, like reference material. [...] This allows explanation to become discussion, a more relaxed, freer way to consider something. Explanation joins things together. It’s documentation that it makes sense to read while away from the product itself.
I think this happens primarily because the API docs are quite neglected. So, I was thinking: since the next days I'm not extra busy, maybe I can open a parallel PR draft on bevy to enrich the API docs in the points where they are referenced by the book.
Agreed. This helps dramatically.
That sounds useful, thanks. |
|
I don't know if you already know it, but you can link the source to docs.rs instead of GitHub. Example: https://docs.rs/bevy_internal/latest/src/bevy_internal/default_plugins.rs.html#3 |
|
Hmm. The docs.rs source links are interesting. I'm not sure if I like them more or less than the GitHub links. They're more idiomatic, but make it harder to explore related code. |
|
I found a couple of pitfalls with the docs.rs source links, that can be fortunately avoided:
Solving issue number 2 limits the docs navigation to only the subcrate though. This may not be a huge issue but it will be a bit frustrating for the user that has to manually go to docs.rs and select the main bevy crate to see stuff on other crates. This can be solved by hosting the docs on the website and building them with dependencies (which is by default). This will put on us some responsibility, but the benefits of having the complete docs outweights the cost IMO. Example of self-hosted API docs: Looks like it's possible to limit documenting dependencies to the local crates 🤔. |
|
For 2, this is why I'm careful to link to the original definition :) Do you think it's better to link to docs.rs over GitHub then? |
|
To me, it looks better and it's more tightly coupled with the docs. The important thing though, is that we link to the API item and not the lines of code. Otherwise, we should manually check each link at each update to ensure it's still updated. |
cart
force-pushed
the
new-book
branch
2 times, most recently
from
04bc036
to
477268e
Compare
Yep, I'm perfectly content to have you do tweaks like that directly :) |
| While Bevy's modular architecture makes it relatively easy to integrate your own (or third-party) solutions, be mindful that Bevy does not provide a complete game solution out of the box *yet*. | ||
| [Contributions to the engine](https://github.com/bevyengine/bevy/) are extremely welcome, but if you want something fully-featured to make your dream game *today*, check out [Godot](https://godotengine.org/) instead! | ||
|
|
||
| Unsurprisingly, Bevy's rapid pace of development means that our APIs will break, repeatedly, in both deep and pervasive ways. |
There was a problem hiding this comment.
One thing to consider: Rust is often considered to be in line with "if it compiles, it works" - however, I think bevy is not matured there yet. Maybe a good to mention in docs?
(920+ unwrap() or panic!'s in code currently - I've personally been caught by a surprise few times to runtime crashes)
There was a problem hiding this comment.
That's probably a good caveat. Compared to other game engines, it's surprisingly "if it compiles it works". But much less so for people coming to games from the Rust ecosystem!
There was a problem hiding this comment.
I think "if it compiles, it works" is an unrealistic goal because Rust's static guarantees are just a subset of its capabilities. I also don't think that "number of unwraps" is a particularly good measure of code maturity. There are plenty of cases where the only real option is an internal unwrap.
That being said, except in a few specific cases, Bevy internals shouldn't crash from normal "userspace" code (and they do currently in a number of cases).
Its worth calling out that Bevy currently has more rough edges / bugs / crashes than a stable product would. However this page is also the first thing Bevy users will see and I consider it a key part of "Bevy marketing". We should do it in a way that doesn't (1) scare people away or (2) give the wrong impression about our goals and priorities. Feel free to add a line here, but (as I've already warned @alice-i-cecile) I have a lot of very specific goals for this page and I'll probably follow this pr up with a lot of changes.
There was a problem hiding this comment.
except in a few specific cases
Are these cases outlined elsewhere? While I agree that they shouldn't be listed on the first welcome page, perhaps a link to the "rough edges" would be appropriate.
There was a problem hiding this comment.
There was good discussion in Discord about the unwrap's as well yesterday. I agree that there will be unwraps, and some of them are totally okay as well (e.g. when starting app, during development work). Also, of the 920+ quite many seemed to be in the tests code, which I did not consider when grepping.
Good point about the marketing, maybe the extra warning should not be yet - the section header "Stability warning" already gives a hint about it.
Also, over time the runtime panic's will get lower and lower. However, I would still be very mindful of this, since an unanticipated runtime panic at wrong point (e.g. demo time, or in production) will quickly turn new adopters away.
There was a problem hiding this comment.
Are these cases outlined elsewhere? While I agree that they shouldn't be listed on the first welcome page, perhaps a link to the "rough edges" would be appropriate.
They are not. It will be hard to maintain the list unless it integrates directly with the issue tracker. Maybe we should have a label for "UX speedbumps". We can link to that specific label. And that way whenever we resolve an issue, the list is automatically updated.
|
After handling @mirkoRainer's comments, I think we can probably merge this. Gotta start moving forward and we can always iterate on this later. |
Examples that crash are bad.
|
Done! I'm not thrilled with the new example (it mostly duplicates the line above and will spam the user's console), but we can modify it later in a small follow-up PR. |
…vy Book (#2365) ## Objective The upcoming Bevy Book makes many references to the API documentation of bevy. Most references belong to the first two chapters of the Bevy Book: - bevyengine/bevy-website#176 - bevyengine/bevy-website#182 This PR attempts to improve the documentation of `bevy_ecs` and `bevy_app` in order to help readers of the Book who want to delve deeper into technical details. ## Solution - Add crate and level module documentation - Document the most important items (basically those included in the preludes), with the following style, where applicable: - **Summary.** Short description of the item. - **Second paragraph.** Detailed description of the item, without going too much in the implementation. - **Code example(s).** - **Safety or panic notes.** ## Collaboration Any kind of collaboration is welcome, especially corrections, wording, new ideas and guidelines on where the focus should be put in. --- ### Related issues - Fixes #2246
|
Alright @cart et al., this is good for a final review round now. The examples aren't automatically compiled yet, but I'd prefer to leave that to a seperate PR. I've tried to poke at it a couple times now and couldn't quite get it working and I think it's wiser to focus on writing and editing work. |
|
|
||
| For the fastest iterative compile times, we recommend the following configuration as well. You need to follow all three steps for any effect: | ||
|
|
||
| 1. **LLD linker**: The Rust compiler spends a lot of time in the "link" step. LLD is _much faster_ at linking than the default Rust linker. To install LLD, find your OS below and run the given command: |
There was a problem hiding this comment.
Maybe also suggest using mold for people using linux
| ``` | ||
|
|
||
| * **MacOS**: Modern LLD does not yet support MacOS, but we can use zld instead: `brew install michaeleisel/zld/zld` | ||
| 2. **Nightly Rust Compiler**: This gives access to the latest performance improvements and "unstable" optimizations |
There was a problem hiding this comment.
I think this step should clearly be marked as optional or at least be more obvious that this is purely for compilation speed and that bevy doesn't require nightly to work. Bevy works without any issues on stable rust so I wouldn't want anyone to think they need nightly.
| So, what sort of data does our {{rust_type(type="struct" crate="bevy" mod = "app" name="App" no_mod = "true")}} really store? | ||
| Looking at the docs linked, we find three fields: `world`, `schedule` and `runner`. | ||
| The `world` field stores all of our game's data, the `schedule` holds the systems that operate on this data (and the order in which they do so) and the `runner` interprets the schedule to control the broad execution strategy. | ||
| You can read more about these by exploring the reference documentation linked just above. |
There was a problem hiding this comment.
It is not immediately obvious to me which documentation link this is referencing. I think adding an actual link here would be better.
|
Merging this as I think its in a reasonable spot. But before publishing this, I'd still like to do a pass over the introduction, because as I mentioned 7.5 months ago (!!!!!! sorry sorry sorry !!!!!), it is kind of like the front page of the website and I'd like to have firm control over how Bevy is introduced. |
Agreed! We'll do a proper pass before publication. |
Welcome to the Welcome Chapter! This is good to go now from my perspective :) The code sample embedding can be a seperate PR: I'd rather not block forever on that.
TODO:
cargo runin the book should be *after* dependencies bevy#2773