Initial draft of upstreaming guidance#2376
Initial draft of upstreaming guidance#2376alice-i-cecile wants to merge 5 commits intobevyengine:mainfrom
Conversation
alice-i-cecile
added
C-Content
X-Controversial
| - this is particularly true for other crates which rely on `bevy`! | ||
| - have clear and helpful documentation and examples, ideally at the crate, module and API level | ||
| - offer the basic functionality expected by users trying to do the thing the crate was made to do | ||
| - have a pleasant API that feels Bevy-idiomatic |
There was a problem hiding this comment.
May be worth mentioning what qualifies something as bevy-idiomatic so that users wanting to upstream know what to aim for?
There was a problem hiding this comment.
| - have a pleasant API that feels Bevy-idiomatic | |
| - have a pleasant API that feels Bevy-idiomatic | |
| - makes use of existing ECS primitives where possible: entities, components, resources, events... | |
| - prefers simple patterns and avoids new abstractions | |
| - defaults to relatively public internals | |
| - uses enums and new-types to encode intent, rather than relying on argument names | |
| - minimizes use of macros |
There was a problem hiding this comment.
This could have an entire document of its own! I think what makes something "Bevy-idiomatic" is also a moving target.
Although maybe something like "APIs should be expressed in the vocabulary of Bevy's ECS" would be enough. A touch vague, but slightly more substantial.
There was a problem hiding this comment.
Yeah, I wanted to stick to some reasonably tangible and uncontroversial elements here. This one has more subjectivity than most!
That said, a lot of the most serious problems here that I've seen in various ecosystem crates aren't actually about their ECS usage at all: it's about weird idioms translated from non-Rust languages!
Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>
7 participants
There's been a number of upstreaming initiatives at this point, some of which have gone better than others. Similarly, we've had a number of folks ask about "what about upstreaming this crate?".
Writing out the guidance lets us agree on principles / best practices in general, and helps teach folks what to think about and how they can help.