search

bevyengine / bevy

A refreshingly simple data-driven game engine built in Rust
https://bevyengine.org
Apache License 2.0
35k stars 3.43k forks source link

Add an ARCHITECTURE.md to the repo #5107

Open PrototypeNM1 opened 2 years ago

PrototypeNM1 commented 2 years ago

Currently it is difficult to get a "big picture" understanding of Bevy's code base. Adding an ARCHITECTURE.md - described by Maklad here - would be a good first step toward providing mental scaffolding.

This was previously brought up in the CONTRIBUTING.md issue.

alice-i-cecile commented 2 years ago

I'm not entirely convinced this should exist. It's hard to maintain, high visibility and requires a lot of expertise to write.

What would you want to see in this?

Nilirad commented 2 years ago

I gave it a look, and it looks like that it's so high level that it doesn't require constant maintenance. I'm not particularly convinced to put it as a separate piece of information. I would rather include it in elsewhere. I think the bevy crate-level documentation would be a not perfect, but good place.

alice-i-cecile commented 2 years ago

I prefer that. I would also like to make sure we have good READMEs for each of the non-standard folders in the repo, and eventually eliminate the top level docs folder completely.

Nilirad commented 2 years ago

I would also like to make sure we have good READMEs for each of the non-standard folders in the repo

Maybe crates/README.md could be used to give a bird's eye view of the architecture of the codebase, like rust-analyzer does with ARCHITECTURE.md

alice-i-cecile commented 2 years ago

I think that's a nice place for that information :)

Nilirad commented 2 years ago

Also a nice excuse to put the bevy crate in that folder too 😏 I think an issue/PR was opened at least once about that.

PrototypeNM1 commented 2 years ago

What would you want to see in this?

A code map is the important part. What are the workspaces, how are they tied together, what's making them tick (at a high level).

Maybe crates/README.md could be used to give a bird's eye view of the architecture of the codebase, like rust-analyzer does with ARCHITECTURE.md

This would probably work. The key points are this should be maximally discoverable and should form a basis to which an understanding of Bevy can start being hung off of. I think a good example of the target specificity would be Blender's code layout and directories explained.

Nilirad commented 2 years ago

The Blender code layout just gave me the idea that we could have a diagram of all the in-engine plugins all grouped by feature.

Another thing that can be taken is the layered approach: core, reflect and tasks on the bottom; ecs and app in the middle; and all the plugins on the top.