mirror of
https://github.com/bevyengine/bevy
synced 2024-11-10 07:04:33 +00:00
Added API guidelines to CONTRIBUTING.md (#3646)
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 <KDecayMusic@protonmail.com>
This commit is contained in:
parent
8e1f660e1d
commit
71814ca91b
1 changed files with 27 additions and 1 deletions
28
.github/contributing/engine_style_guide.md
vendored
28
.github/contributing/engine_style_guide.md
vendored
|
@ -1,6 +1,10 @@
|
|||
# Style guide: Engine
|
||||
|
||||
For more advice on contributing to the engine, see the [relevant section](../../CONTRIBUTING.md#Contributing-your-own-ideas) of CONTRIBUTING.md.
|
||||
## Contributing
|
||||
|
||||
For more advice on contributing to the engine, see the [relevant section](../../CONTRIBUTING.md#Contributing-your-own-ideas) of `CONTRIBUTING.md`.
|
||||
|
||||
## General guidelines
|
||||
|
||||
1. Prefer granular imports over glob imports of `bevy::prelude::*` and `bevy::sub_crate::*`.
|
||||
2. Use a consistent comment style:
|
||||
|
@ -10,3 +14,25 @@ For more advice on contributing to the engine, see the [relevant section](../../
|
|||
4. Use \`variable_name\` code blocks in comments to signify that you're referring to specific types and variables.
|
||||
5. Start comments with capital letters. End them with a period if they are sentence-like.
|
||||
3. Use comments to organize long and complex stretches of code that can't sensibly be refactored into separate functions.
|
||||
|
||||
## Rust API guidelines
|
||||
|
||||
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:
|
||||
|
||||
### Areas of disagreements
|
||||
|
||||
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.
|
||||
|
||||
> All items have a rustdoc example
|
||||
|
||||
- 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.
|
||||
|
||||
> Examples use ?, not try!, not unwrap
|
||||
|
||||
- This guideline is usually reasonable, but not always required.
|
||||
|
||||
> Only smart pointers implement Deref and DerefMut
|
||||
|
||||
- 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.
|
||||
|
||||
[Rust API guidelines]: https://rust-lang.github.io/api-guidelines/about.html
|
||||
|
|
Loading…
Reference in a new issue