Initial draft of upstreaming guidance#2376
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>
| - Bevy has no existing solution for this problem | ||
| - the scope of a game engine is large, but not infinite | ||
| - each feature must justify its value relative to the maintenance/compile time/binary size costs | ||
| - Bevy is intentionally very extensible: allowing users to |
There was a problem hiding this comment.
I think this might be in the wrong place?
There was a problem hiding this comment.
@alice-i-cecile I think this was overlooked
|
Mermaid diagram: quadrantChart
title Upstream decision framework
x-axis "Not to upstream" --> "To upstream"
y-axis "Bad reasons" --> "Good reasons"
quadrant-1 Good reasons to upstream
quadrant-2 Good reasons not to upstream
quadrant-3 Bad reasons not to upstream
quadrant-4 Bad reasons to upstream
|
Co-authored-by: weihnaxbaum <140716472+weihnaxbaum@users.noreply.github.com>
cart
left a comment
cart
left a comment
There was a problem hiding this comment.
Solid work! Just one minor point of contention :)
11 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.