You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Closes#3497.
I added the rust API guidelines (https://rust-lang.github.io/api-guidelines/about.html) to the `CONTRIBUTING.md` file.
## Note
As noted in #3497 we should note any areas where we deliberately disagree as they arise. If we start adding these areas it might be a good idea to remove the mention of the `API guidelines` in the `CONTRIBUTING.md` file and move it to the `engine_style_guide.md`. That way we still have the connection between the `CONTRIBUTING.md` and the `API guidelines`, but we have more "space" to work with and can go into more detail about what we agree and disagree on.
For now I would leave it this way, because it's one less click to get to the guidelines.
Co-authored-by: KDecay <[email protected]>
Copy file name to clipboardExpand all lines: .github/contributing/engine_style_guide.md
+27-1Lines changed: 27 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,10 @@
1
1
# Style guide: Engine
2
2
3
-
For more advice on contributing to the engine, see the [relevant section](../../CONTRIBUTING.md#Contributing-your-own-ideas) of CONTRIBUTING.md.
3
+
## Contributing
4
+
5
+
For more advice on contributing to the engine, see the [relevant section](../../CONTRIBUTING.md#Contributing-your-own-ideas) of `CONTRIBUTING.md`.
6
+
7
+
## General guidelines
4
8
5
9
1. Prefer granular imports over glob imports of `bevy::prelude::*` and `bevy::sub_crate::*`.
6
10
2. Use a consistent comment style:
@@ -10,3 +14,25 @@ For more advice on contributing to the engine, see the [relevant section](../../
10
14
4. Use \`variable_name\` code blocks in comments to signify that you're referring to specific types and variables.
11
15
5. Start comments with capital letters. End them with a period if they are sentence-like.
12
16
3. Use comments to organize long and complex stretches of code that can't sensibly be refactored into separate functions.
17
+
18
+
## Rust API guidelines
19
+
20
+
As a reference for our API development we are using the [Rust API guidelines][Rust API guidelines]. Generally, these should be followed, except for the following areas of disagreement:
21
+
22
+
### Areas of disagreements
23
+
24
+
Some areas mentioned in the [Rust API guidelines][Rust API guidelines] we do not agree with. These areas will be expanded whenever we find something else we do not agree with, so be sure to check these from time to time.
25
+
26
+
> All items have a rustdoc example
27
+
28
+
- This guideline is too strong and not applicable for everything inside of the Bevy game engine. For functionality that requires more context or needs a more interactive demonstration (such as rendering or input features), make use of the `examples` folder instead.
29
+
30
+
> Examples use ?, not try!, not unwrap
31
+
32
+
- This guideline is usually reasonable, but not always required.
33
+
34
+
> Only smart pointers implement Deref and DerefMut
35
+
36
+
- Generally a good rule of thumb, but we're probably going to deliberately violate this for single-element wrapper types like `Life(u32)`. The behavior is still predictable and it significantly improves ergonomics / new user comprehension.
37
+
38
+
[Rust API guidelines]: https://rust-lang.github.io/api-guidelines/about.html
0 commit comments