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
[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>
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+47-48Lines changed: 47 additions & 48 deletions
Original file line number
Diff line number
Diff line change
@@ -8,10 +8,10 @@ It's a nice place to chat about Bevy development, ask questions, and get to know
8
8
9
9
Read on if you're looking for:
10
10
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.
15
15
16
16
We're thrilled to have you along as we build!
17
17
@@ -40,20 +40,20 @@ Some crates of interest:
40
40
41
41
Bevy is a completely free and open source game engine built in Rust. It currently has the following design goals:
42
42
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.
49
49
50
50
Bevy also currently has the following "development process" goals:
51
51
52
52
***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.
53
53
***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.
54
54
***Flexibility over bureaucracy**: Developers should feel productive and unencumbered by development processes.
55
55
***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.
57
57
***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.
58
58
***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.
59
59
***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.
*[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).
@@ -253,23 +253,22 @@ which has the latest API reference built from the repo on every commit made to t
253
253
254
254
### Writing examples
255
255
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.
259
258
260
-
Examples in Bevyshouldbe:
259
+
Examples in Bevyshouldbe:
261
260
262
-
1.**Working:**Theymustcompileandrun,andany introduced errors in them should be obvious(through tests, simple results or clearly displayed behavior).
263
-
2.**Clear:**Theymustusedescriptivevariablenames, be formatted,and be appropriatelycommented. Try your best to showcase best practices when it doesn't obscure the point of the example.
264
-
3.**Relevant:**Theyshouldexplain, through comments or variable names, what they do and how this can be useful to a game developer.
265
-
4.**Minimal:** Theyshould be no larger or complexthan is needed to meet the goals of the example.
261
+
1.**Working:**Theymustcompileandrun,andany introduced errors in them should be obvious(through tests, simple results or clearly displayed behavior).
262
+
2.**Clear:**Theymustusedescriptivevariablenames, be formatted,and be appropriatelycommented. Try your best to showcase best practices when it doesn't obscure the point of the example.
263
+
3.**Relevant:**Theyshouldexplain, through comments or variable names, what they do and how this can be useful to a game developer.
264
+
4.**Minimal:** Theyshould be no larger or complexthan is needed to meet the goals of the example.
266
265
267
266
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.
268
267
Run `cargo run -p build-templated-pages -- build-example-page` to do this automatically.
269
268
Use a generous sprinkling of keywords in your description: these are commonly used to search for a specific example.
270
269
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.
271
270
272
-
Morecomplexdemonstrations of functionalityarealsowelcome, but these should be submitted to [bevy-assets](https://github.com/bevyengine/bevy-assets).
271
+
Morecomplexdemonstrations of functionalityarealsowelcome, but these should be submitted to [bevy-assets](https://github.com/bevyengine/bevy-assets).
273
272
274
273
### Reviewing others' work
275
274
@@ -289,7 +288,7 @@ If you're new to GitHub, check out the [Pull Request Review documentation](https
289
288
290
289
There are three main places you can check for things to review:
291
290
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).
293
292
2. Pull requests on [bevy](https://github.com/bevyengine/bevy/pulls) and the [bevy-website](https://github.com/bevyengine/bevy-website/pulls) repos.
294
293
3.[RFCs](https://github.com/bevyengine/rfcs), which need extensive thoughtful community input on their design.
295
294
@@ -329,11 +328,11 @@ If you're new to Bevy, here's the workflow we use:
329
328
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.
330
329
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.
331
330
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).
337
336
338
337
4. When working with Markdown (`.md`) files, Bevy's CI will check markdown files (like this one) using [markdownlint](https://github.com/DavidAnson/markdownlint).
339
338
To locally lint your files using the same workflow as our CI:
0 commit comments