Document Bevy crate tiers and expectations

[mockersf]

Bevy has many crates, with various level of expectations. I would like those levels to be documented, with their expectations and where they currently stand.

I think the current status is:

• Tier 1: bevy!
  • Code must compile on all platforms (macos, windows, linux, android, ios, wasm)
  • Features must be documented
  • Examples must be documented
  • Selected examples must run on all platforms
• Tier 2: standalone crates: bevy_ecs, bevy_reflect, bevy_color, ...
  • If the crate has unsafe code, run through miri
  • If the crate can build in no std, check it
  • Build without default features
• Tier 3: all the others
  • Not much

Tier 3 is mostly useful to plugin authors and power users, and is lacking in documentation. For example, documenting features of all crates would have a lot of value.

Things to do:

• document current state
• agree on expectations

[alice-i-cecile]

I don't like the numbered tiers, but I agree that a categorization system would be useful!

Proposal:

• core: part of Bevy's default feature set, used to create a cohesive game engine. These must work on all platforms, be fully documented and so on.
• standalone: crates that can be used on their own but are designed specifically for Bevy. Cannot pull in bevy_ecs.
• utility: small, stable crates that Bevy happens to maintain, but are not actually tied to Bevy. These belong in the Bevy org but not the Bevy repo.
• optional: game engine functionality that isn't used by many games. Meshlets for example belong here, as would something like tilemap support. Most of the editor-supporting crates and dev tools seem like they belong here too.

[bushrat011899]

I think this would be excellent to codify. With no_std support (hopefully) growing in the next release, it might be prudent to split core into two labels: core and standard. core would apply to anything that compiles in no_std (bevy_ecs, bevy_app, etc.), while standard is a superset of core and would include things like bevy_audio and bevy_render. I think this also overlaps quite nicely with the distinction between core and std within Rust itself.

[alice-i-cecile]

This came up again today in the context of upstreaming various editor components as crates.

Part of me wants to organize the various crates into subfolders based on this schema, but it would be incredibly breaking for various links and PRs, so it's probably not worth it.

[bushrat011899]

Part of me wants to organize the various crates into subfolders based on this schema, but it would be incredibly breaking for various links and PRs, so it's probably not worth it.

It might be worth considering adopting some metadata within the various Cargo.toml files like what the Rust Playground does to document things like what features should be enabled. Could potentially do something like:

[package.metadata.bevy]
kind = "core" # "standalone", "utility", "optional", etc.

Could then configure various CI tasks to read this kind field to determine what tests should be run (e.g., "core" crates can forbid(missing_docs), etc.). Once these labels are fleshed out, a more serious breaking change could move them into separate folders, but it might not be required if it's "easy" to read the Cargo.toml and know what level of support a crate has.

[alice-i-cecile]

Ah perfect, I was hoping that we could add arbitrary metadata to the Cargo.toml :D