Skip to content

Commit 8db4723

Browse files
Architector4alice-i-cecilerparrett
authored
[doc] Fix typo and formatting in CONTRIBUTING.md (#11381)
# Objective Issue: There is a typo in `CONTRIBUTING.md` ("then" used in place of "them"). There is also an inconsistency of usage of periods at ends of items in lists, and one section is written with non-breaking spaces without good reason. ## Solution Fix the aforementioned typo and consistency issues. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: Rob Parrett <robparrett@gmail.com>
1 parent 30940e5 commit 8db4723

File tree

1 file changed

+47
-48
lines changed

1 file changed

+47
-48
lines changed

CONTRIBUTING.md

Lines changed: 47 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ It's a nice place to chat about Bevy development, ask questions, and get to know
88

99
Read on if you're looking for:
1010

11-
* the high-level design goals of Bevy
12-
* conventions and informal practices we follow when developing Bevy
13-
* general advice on good open source collaboration practices
14-
* concrete ways you can help us, no matter your background or skill level
11+
* The high-level design goals of Bevy.
12+
* Conventions and informal practices we follow when developing Bevy.
13+
* General advice on good open source collaboration practices.
14+
* Concrete ways you can help us, no matter your background or skill level.
1515

1616
We're thrilled to have you along as we build!
1717

@@ -40,20 +40,20 @@ Some crates of interest:
4040

4141
Bevy is a completely free and open source game engine built in Rust. It currently has the following design goals:
4242

43-
* **Capable**: Offer a complete 2D and 3D feature set
44-
* **Simple**: Easy for newbies to pick up, but infinitely flexible for power users
45-
* **Data Focused**: Data-oriented architecture using the Entity Component System paradigm
46-
* **Modular**: Use only what you need. Replace what you don't like
47-
* **Fast**: App logic should run quickly, and when possible, in parallel
48-
* **Productive**: Changes should compile quickly ... waiting isn't fun
43+
* **Capable**: Offer a complete 2D and 3D feature set.
44+
* **Simple**: Easy for newbies to pick up, but infinitely flexible for power users.
45+
* **Data Focused**: Data-oriented architecture using the Entity Component System paradigm.
46+
* **Modular**: Use only what you need. Replace what you don't like.
47+
* **Fast**: App logic should run quickly, and when possible, in parallel.
48+
* **Productive**: Changes should compile quickly ... waiting isn't fun.
4949

5050
Bevy also currently has the following "development process" goals:
5151

5252
* **Rapid experimentation over API stability**: We need the freedom to experiment and iterate in order to build the best engine we can. This will change over time as APIs prove their staying power.
5353
* **Consistent vision**: The engine needs to feel consistent and cohesive. This takes precedence over democratic and/or decentralized processes. See our [*Bevy Organization doc*](/docs/the_bevy_organization.md) for more details.
5454
* **Flexibility over bureaucracy**: Developers should feel productive and unencumbered by development processes.
5555
* **Focus**: The Bevy Org should focus on building a small number of features excellently over merging every new community-contributed feature quickly. Sometimes this means pull requests will sit unmerged for a long time. This is the price of focus and we are willing to pay it. Fortunately Bevy is modular to its core. 3rd party plugins are a great way to work around this policy.
56-
* **User-facing API ergonomics come first**: Solid user experience should receive significant focus and investment. It should rarely be compromised in the interest of internal implementation details.
56+
* **User-facing API ergonomics come first**: Solid user experience should receive significant focus and investment. It should rarely be compromised in the interest of internal implementation details.
5757
* **Modularity over deep integration**: Individual crates and features should be "pluggable" whenever possible. Don't tie crates, features, or types together that don't need to be.
5858
* **Don't merge everything ... don't merge too early**: Every feature we add increases maintenance burden and compile times. Only merge features that are "generally" useful. Don't merge major changes or new features unless we have relative consensus that the design is correct *and* that we have the developer capacity to support it. When possible, make a 3rd party Plugin / crate first, then consider merging once the API has been tested in the wild. Bevy's modular structure means that the only difference between "official engine features" and "third party plugins" is our endorsement and the repo the code lives in. We should take advantage of that whenever possible.
5959
* **Control and consistency over 3rd party code reuse**: Only add a dependency if it is *absolutely* necessary. Every dependency we add decreases our autonomy and consistency. Dependencies also have the potential to increase compile times and risk pulling in sub-dependencies we don't want / need.
@@ -78,17 +78,17 @@ Check out our dedicated [Bevy Organization document](/docs/the_bevy_organization
7878

7979
Our merge strategy relies on the classification of PRs on two axes:
8080

81-
* How controversial are the design decisions
82-
* How complex is the implementation
81+
* How controversial are the design decisions.
82+
* How complex is the implementation.
8383

8484
Each [label](https://github.com/bevyengine/bevy/labels) has a prefix denoting its category:
8585

86-
* A: Area (e.g. A-Animation, A-ECS, A-Rendering)
87-
* C: Category (e.g. C-Breaking-Change, C-Code-Quality, C-Docs)
88-
* D: Difficulty (e.g. D-Complex, D-Good-First-Issue)
89-
* O: Operating System (e.g. O-Linux, O-Web, O-Windows)
90-
* P: Priority (e.g. P-Critical, P-High)
91-
* S: Status (e.g. S-Blocked, S-Controversial, S-Needs-Design)
86+
* A: Area (e.g. A-Animation, A-ECS, A-Rendering).
87+
* C: Category (e.g. C-Breaking-Change, C-Code-Quality, C-Docs).
88+
* D: Difficulty (e.g. D-Complex, D-Good-First-Issue).
89+
* O: Operating System (e.g. O-Linux, O-Web, O-Windows).
90+
* P: Priority (e.g. P-Critical, P-High).
91+
* S: Status (e.g. S-Blocked, S-Controversial, S-Needs-Design).
9292

9393
PRs with non-trivial design decisions are given the [`S-Controversial`] label. This indicates that
9494
the PR needs more thorough design review or an [RFC](https://github.com/bevyengine/rfcs), if complex enough.
@@ -97,7 +97,7 @@ PRs that are non-trivial to review are given the [`D-Complex`] label. This indic
9797
should be reviewed more thoroughly and by people with experience in the area that the PR touches.
9898

9999
When making PRs, try to split out more controversial changes from less controversial ones, in order to make your work easier to review and merge.
100-
It is also a good idea to try and split out simple changes from more complex changes if it is not helpful for then to be reviewed together.
100+
It is also a good idea to try and split out simple changes from more complex changes if it is not helpful for them to be reviewed together.
101101

102102
Some things that are reason to apply the [`S-Controversial`] label to a PR:
103103

@@ -106,42 +106,42 @@ Some things that are reason to apply the [`S-Controversial`] label to a PR:
106106
3. Serious tradeoffs were made.
107107
4. Heavy user impact.
108108
5. New ways for users to make mistakes (footguns).
109-
6. Adding a dependency
109+
6. Adding a dependency.
110110
7. Touching licensing information (due to level of precision required).
111-
8. Adding root-level files (due to the high level of visibility)
111+
8. Adding root-level files (due to the high level of visibility).
112112

113113
Some things that are reason to apply the [`D-Complex`] label to a PR:
114114

115-
1. Introduction or modification of soundness relevant code (for example `unsafe` code)
115+
1. Introduction or modification of soundness relevant code (for example `unsafe` code).
116116
2. High levels of technical complexity.
117-
3. Large-scale code reorganization
117+
3. Large-scale code reorganization.
118118

119119
Examples of PRs that are not [`S-Controversial`] or [`D-Complex`]:
120120

121121
* Fixing dead links.
122122
* Removing dead code or unused dependencies.
123123
* Typo and grammar fixes.
124-
* [Add `Mut::reborrow`](https://github.com/bevyengine/bevy/pull/7114)
125-
* [Add `Res::clone`](https://github.com/bevyengine/bevy/pull/4109)
124+
* [Add `Mut::reborrow`](https://github.com/bevyengine/bevy/pull/7114).
125+
* [Add `Res::clone`](https://github.com/bevyengine/bevy/pull/4109).
126126

127127
Examples of PRs that are [`S-Controversial`] but not [`D-Complex`]:
128128

129-
* [Implement and require `#[derive(Component)]` on all component structs](https://github.com/bevyengine/bevy/pull/2254)
130-
* [Use default serde impls for Entity](https://github.com/bevyengine/bevy/pull/6194)
129+
* [Implement and require `#[derive(Component)]` on all component structs](https://github.com/bevyengine/bevy/pull/2254).
130+
* [Use default serde impls for Entity](https://github.com/bevyengine/bevy/pull/6194).
131131

132132
Examples of PRs that are not [`S-Controversial`] but are [`D-Complex`]:
133133

134-
* [Ensure `Ptr`/`PtrMut`/`OwningPtr` are aligned in debug builds](https://github.com/bevyengine/bevy/pull/7117)
135-
* [Replace `BlobVec`'s `swap_scratch` with a `swap_nonoverlapping`](https://github.com/bevyengine/bevy/pull/4853)
134+
* [Ensure `Ptr`/`PtrMut`/`OwningPtr` are aligned in debug builds](https://github.com/bevyengine/bevy/pull/7117).
135+
* [Replace `BlobVec`'s `swap_scratch` with a `swap_nonoverlapping`](https://github.com/bevyengine/bevy/pull/4853).
136136

137137
Examples of PRs that are both [`S-Controversial`] and [`D-Complex`]:
138138

139-
* [bevy_reflect: Binary formats](https://github.com/bevyengine/bevy/pull/6140)
139+
* [bevy_reflect: Binary formats](https://github.com/bevyengine/bevy/pull/6140).
140140

141141
Some useful pull request queries:
142142

143-
* [PRs which need reviews and are not `D-Complex`](https://github.com/bevyengine/bevy/pulls?q=is%3Apr+-label%3AD-Complex+-label%3AS-Ready-For-Final-Review+-label%3AS-Blocked++)
144-
* [`D-Complex` PRs which need reviews](https://github.com/bevyengine/bevy/pulls?q=is%3Apr+label%3AD-Complex+-label%3AS-Ready-For-Final-Review+-label%3AS-Blocked)
143+
* [PRs which need reviews and are not `D-Complex`](https://github.com/bevyengine/bevy/pulls?q=is%3Apr+-label%3AD-Complex+-label%3AS-Ready-For-Final-Review+-label%3AS-Blocked++).
144+
* [`D-Complex` PRs which need reviews](https://github.com/bevyengine/bevy/pulls?q=is%3Apr+label%3AD-Complex+-label%3AS-Ready-For-Final-Review+-label%3AS-Blocked).
145145

146146
[`S-Controversial`]: https://github.com/bevyengine/bevy/pulls?q=is%3Aopen+is%3Apr+label%3AS-Controversial
147147
[`D-Complex`]: https://github.com/bevyengine/bevy/pulls?q=is%3Aopen+is%3Apr+label%3AD-Complex
@@ -253,23 +253,22 @@ which has the latest API reference built from the repo on every commit made to t
253253

254254
### Writing examples
255255

256-
Most [examples in Bevy](https://github.com/bevyengine/bevy/tree/main/examples) aim to clearly demonstrate a single feature, group of closely related small features, or show how to accomplish a particular task (such as asset loading, creating a custom shader or testing your app).
257-
In rare cases, creating new "game" examples is justified in order to demonstrate new features
258-
that open a complex class of functionality in a way that's hard to demonstrate in isolation or requires additional integration testing.
256+
Most [examples in Bevy](https://github.com/bevyengine/bevy/tree/main/examples) aim to clearly demonstrate a single feature, group of closely related small features, or show how to accomplish a particular task (such as asset loading, creating a custom shader or testing your app).
257+
In rare cases, creating new "game" examples is justified in order to demonstrate new features that open a complex class of functionality in a way that's hard to demonstrate in isolation or requires additional integration testing.
259258

260-
Examples in Bevy should be:
259+
Examples in Bevy should be:
261260

262-
1. **Working:** They must compile and run, and any introduced errors in them should be obvious (through tests, simple results or clearly displayed behavior).
263-
2. **Clear:** They must use descriptive variable names, be formatted, and be appropriately commented. Try your best to showcase best practices when it doesn't obscure the point of the example.
264-
3. **Relevant:** They should explain, through comments or variable names, what they do and how this can be useful to a game developer.
265-
4. **Minimal:** They should be no larger or complex than is needed to meet the goals of the example.
261+
1. **Working:** They must compile and run, and any introduced errors in them should be obvious (through tests, simple results or clearly displayed behavior).
262+
2. **Clear:** They must use descriptive variable names, be formatted, and be appropriately commented. Try your best to showcase best practices when it doesn't obscure the point of the example.
263+
3. **Relevant:** They should explain, through comments or variable names, what they do and how this can be useful to a game developer.
264+
4. **Minimal:** They should be no larger or complex than is needed to meet the goals of the example.
266265

267266
When you add a new example, be sure to update `examples/README.md` with the new example and add it to the root `Cargo.toml` file.
268267
Run `cargo run -p build-templated-pages -- build-example-page` to do this automatically.
269268
Use a generous sprinkling of keywords in your description: these are commonly used to search for a specific example.
270269
See the [example style guide](.github/contributing/example_style_guide.md) to help make sure the style of your example matches what we're already using.
271270

272-
More complex demonstrations of functionality are also welcome, but these should be submitted to [bevy-assets](https://github.com/bevyengine/bevy-assets).
271+
More complex demonstrations of functionality are also welcome, but these should be submitted to [bevy-assets](https://github.com/bevyengine/bevy-assets).
273272

274273
### Reviewing others' work
275274

@@ -289,7 +288,7 @@ If you're new to GitHub, check out the [Pull Request Review documentation](https
289288

290289
There are three main places you can check for things to review:
291290

292-
1. Pull request which are ready and in need of more reviews on [bevy](https://github.com/bevyengine/bevy/pulls?q=is%3Aopen+is%3Apr+-label%3AS-Ready-For-Final-Review+-draft%3A%3Atrue+-label%3AS-Needs-RFC+-reviewed-by%3A%40me+-author%3A%40me)
291+
1. Pull requests which are ready and in need of more reviews on [bevy](https://github.com/bevyengine/bevy/pulls?q=is%3Aopen+is%3Apr+-label%3AS-Ready-For-Final-Review+-draft%3A%3Atrue+-label%3AS-Needs-RFC+-reviewed-by%3A%40me+-author%3A%40me).
293292
2. Pull requests on [bevy](https://github.com/bevyengine/bevy/pulls) and the [bevy-website](https://github.com/bevyengine/bevy-website/pulls) repos.
294293
3. [RFCs](https://github.com/bevyengine/rfcs), which need extensive thoughtful community input on their design.
295294

@@ -329,11 +328,11 @@ If you're new to Bevy, here's the workflow we use:
329328
1. Try to split your work into separate commits, each with a distinct purpose. Be particularly mindful of this when responding to reviews so it's easy to see what's changed.
330329
2. Tip: [You can set up a global `.gitignore` file](https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files#configuring-ignored-files-for-all-repositories-on-your-computer) to exclude your operating system/text editor's special/temporary files. (e.g. `.DS_Store`, `thumbs.db`, `*~`, `*.swp` or `*.swo`) This allows us to keep the `.gitignore` file in the repo uncluttered.
331330
3. To test CI validations locally, run the `cargo run -p ci` command. This will run most checks that happen in CI, but can take some time. You can also run sub-commands to iterate faster depending on what you're contributing:
332-
* `cargo run -p ci -- lints` - to run formatting and clippy
333-
* `cargo run -p ci -- test` - to run tests
334-
* `cargo run -p ci -- doc` - to run doc tests and doc checks
335-
* `cargo run -p ci -- compile` - to check that everything that must compile still does (examples and benches), and that some that shouldn't still don't ([`crates/bevy_ecs_compile_fail_tests`](./crates/bevy_ecs_compile_fail_tests))
336-
* to get more information on commands available and what is run, check the [tools/ci crate](./tools/ci)
331+
* `cargo run -p ci -- lints` - to run formatting and clippy.
332+
* `cargo run -p ci -- test` - to run tests.
333+
* `cargo run -p ci -- doc` - to run doc tests and doc checks.
334+
* `cargo run -p ci -- compile` - to check that everything that must compile still does (examples and benches), and that some that shouldn't still don't ([`crates/bevy_ecs_compile_fail_tests`](./crates/bevy_ecs_compile_fail_tests)).
335+
* to get more information on commands available and what is run, check the [tools/ci crate](./tools/ci).
337336

338337
4. When working with Markdown (`.md`) files, Bevy's CI will check markdown files (like this one) using [markdownlint](https://github.com/DavidAnson/markdownlint).
339338
To locally lint your files using the same workflow as our CI:

0 commit comments

Comments
 (0)