# Objective
Coordinating work can be hard, and figuring out how to get started with
contributions is always a challenge.
We've had great success with informal working groups in the past
(primitives, bevy_color, stageless). However, they're not at all
discoverable, are hard to keep track of and tend to flood the dev
channels that they're in.
When their messages are moved to Discord threads, they then get
completely scattered and buried.
## Solution
We can formalize the working groups in a very process-light way, and
give them a discoverable home by using a curated forum channel on
Discord.
While we'll still need more stringent PR reviews for particularly
complex or architectural changes made as part of these initiatives, a
broad sign off on the course of action goes a long way to building
consensus. By baking that into the process, I think we can avoid a lot
of wasted work and relitigation without encouraging mega-PRs or RFCs.
---------
Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>
# Objective
The existing labels are inadequate for keeping track of the state of
work at a glance. They're also inadequate for finding work that's at an
appropriate difficulty level to either implement or review.
## Solution
- Add a complete set of difficulty labels
- Move `S-Controversial` into its own category
- Adding a complete set of controversiality labels, adding
`X-Uncontroversial` and `X-Contentious`
- Add a complete set of status labels: adding `S-Needs-Testing`,
`S-Needs-Review` and `S-Waiting-On-Author`
- Update CONTRIBUTING.md to reflect the new scheme
---------
Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>
# Objective
- Bevy has a large number of open PRs in the backlog.
- When there are problems with these PRs, contributors, maintainers and
SMEs are all often left wondering what to do with them and are reluctant
to close them fully.
- Instead, PRs that are a bad idea end up sititng with Controversial
status forever, while severely rotten PRs have Adopt-Me on them when it
would be more appropriate to simply remake them.
## Solution
- Add clear guidance on how and when to close PRs.
---------
Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
Co-authored-by: BD103 <59022059+BD103@users.noreply.github.com>
# Objective
Requesting reviews is a useful tool for improving discoverability of PRs
that contributors might be interested in and capable of reviewing.
However, many Bevy org members and authors aren't aware that they can
and should request reviews.
## Solution
Actually document that this is good practice, and remind people that
it's just a nudge.
---------
Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
# Objective
Reviews with caveats are incredibly useful to maintainers when
evaluating PRs.
However, it's not generally clear to reviewers that conditional
approvals or partial approvals are helpful and welcome.
## Solution
Add clarifying documentation to CONTRIBUTING.md.
---------
Co-authored-by: Alice Cecile <alice.i.cecil@gmail.com>
# Objective
- Avoid misspellings throughout the codebase by using
[`typos`](https://github.com/crate-ci/typos) in CI
Inspired by https://github.com/gfx-rs/wgpu/pull/5191
Typos is a minimal code speller written in rust that finds and corrects
spelling mistakes among source code.
- Fast enough to run on monorepos
- Low false positives so you can run on PRs
## Solution
- Use
[typos-action](https://github.com/marketplace/actions/typos-action) in
CI
- Add how to use typos in the Contribution Guide
---------
Co-authored-by: François <mockersf@gmail.com>
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>
# 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>
# Objective
- Standardize fmt for toml files
## Solution
- Add [taplo](https://taplo.tamasfe.dev/) to CI (check for fmt and diff
for toml files), for context taplo is used by the most popular extension
in VScode [Even Better
TOML](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml
- Add contribution section to explain toml fmt with taplo.
Now to pass CI you need to run `taplo fmt --option indent_string=" "` or
if you use vscode have the `Even Better TOML` extension with 4 spaces
for indent
---------
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
# Objective
Bevy provides an easy way to build the `examples/README.md` page, but
it's difficult to discover.
By adding instructions in `CONTRIBUTING.md`, it's easier to find that
it's possible to avoid this error-prone manual process.
Precisely: #8405 took me about 1 additional hour searching what command
to use to generate automatically the file. (I could have manually edited
the README, but that's beyond the point…)
# Objective
Fixes#7704
## Solution
Added a small section that describes the meaning of each letter prefix for issue labels.
Co-authored-by: Adam <59033400+adam-shih@users.noreply.github.com>
# Objective
I found several words in code and docs are incorrect. This should be fixed.
## Solution
- Fix several minor typos
Co-authored-by: Chris Ohk <utilforever@gmail.com>
Current info is not up to date as we are now using a train release model and frequently end up with PRs and issues in the milestone that are not resolved before release. As the release milestone is now mostly used for prioritizing what work gets done I updated this section to be about prioritizing PRs/issues instead of preparing releases.
The current section does not talk about `D-Complex` and lists things like "adds unsafe code" as a reason to mark a PR `S-Controversial`. This is not how `D-Complex` and `S-Controversial` are being used at the moment.
This PR lists what classifies a PR as `D-Complex` and what classifies a PR as `S-Controversial`. It also links to some PRs with each combination of labels to help give an idea for what this means in practice.
cc #7211 which is doing a similar thing
We are in the process of rolling out a new Bevy Organization role! (Subject Matter Expert)
This adds a new "The Bevy Organization" document and links to it from CONTRIBUTING.md. This doc describes how the Bevy Organization will work going forward. It outlines the functionality of each role, as well as the expectations we have for them. The previously existing roles (Project Lead, Maintainer) still work the same way, but their definition and scope have been made much clearer.
Tomorrow we will be announcing this publicly in a blog post. This will describe the motivation and announce the first round of SMEs . But before that it makes sense to do a quick review round first.
Given the quick turnaround on this PR, this isn't the best platform to discuss changes to the SME system (or its validity). After you have read the announcement tomorrow, feel free to start discussions wherever is preferable to you (this repo, discord, etc). So for now, please just review for clarity / typos / phrasing / missed info / etc.
[Rendered](08ceae43db/docs/the_bevy_organization.md)
* Adding a new section concerning the maintainers of the repo
# Objective
- Adding a few helpful links in the CONTRIBUTING.md files
- Fixes#6221
## Solution
- Modifying CONTRIBUTING.md
- Adding a new section dedicated to maintainers in CONTRIBUTING.md
---
Co-authored-by: Ptipiak <Ptipiak.off@gmail.com>
# Objective
Finder in macOS creates hidden `.DS_Store` files containing metadata (for icon positioning, view mode, etc) whenever you browse a directory. There's no point in committing these to git, and they're a common git + macOS nuisance.
## Solution
- ~~This PR adds `.DS_Store` files to `.gitignore`, improving the developer experience on macOS.~~
- This PR adds a note to the `CONTRIBUTING.md` file teaching how to use global git ignore.
# Objective
Fixes#5390. Makes https://dev-docs.bevyengine.org/ a bit more discoverable.
## Solution
Mention the option as an alternative option to building the docs yourself in CONTRIBUTING.md.
# Objective
- In #4966, @DJMcNab noted that the changes should likely have been flagged as controversial, and blocked on a final pass from @cart.
- I think this is generally reasonable.
- Added as an explicit guideline.
- Changes to top-level files are also typically controversial, due to the high visible impact (see #4700 for a case of that).
- Added as an explicit guideline.
- The licensing information of our included assets is hard to find.
- Call out the existence of CREDITS.md
Small nitpicks over my full read over Contributing.md
# Objective
Fixes to Contributing file
- Lists more coherent: starting with capital letter and ending with point.
- Fixed a Typo.
- A clarification on approval aimed at newcomers.
- Reference links
**This Commit**
1. Makes it so the sentence doesn't read "are contributors who have Have
actively ..."
2. Makes it so all three bullet points end in punctuation
**Notes**
Could also remove the leading "Have" from all bullet points and leave it
on the previous sentence. That's the least redundant but I guess this is
more flexible if we want to add a sentence that doesn't start with
"Have" later.
# Objective
- CONTRIBUTING.md references wrong issue label, making it potentially confusing for new contributors.
## Solution
- Update CONTRIBUTING.md.
---
I assume the label was changed recently.
# Objective
- Original objective was to add doc build warning check to the ci local execution
- I somewhat deviated and changed other things...
## Solution
`cargo run -p ci` can now take more parameters:
* `format` - cargo fmt
* `clippy` - clippy
* `compile-fail` - bevy_ecs_compile_fail_tests tests
* `test` - tests but not doc tests and do not build examples
* `doc-test` - doc tests
* `doc-check` - doc build and warnings
* `bench-check` - check that benches build
* `example-check` - check that examples build
* `lints` - group - run lints and format and clippy
* `doc` - group - run doc-test and doc-check
* `compile` - group - run compile-fail and bench-check and example-check
* not providing a parameter will run everything
Ci is using those when possible:
* `build` jobs now don't run doc tests and don't build examples. it makes this job faster, but doc tests and examples are not built for each architecture target
* `ci` job doesn't run the `compile-fail` part but only format and clippy, taking less time
* `check-benches` becomes `check-compiles` and runs the `compile` tasks. It takes longer. I also fixed how it was using cache
* `check-doc` job is now independent and also run the doc tests, so it takes longer. I commented out the deadlinks check as it takes 2.5 minutes (to install) and doesn't work
# Objective
- The strategy for delegation has changed!
- Figuring out exactly where the "controversial" line is can be challenging
## Solution
- Update the CONTRIBUTING.md
- Specify rough guidelines for what makes a PR controversial.
- BONUS: yeet references to old roadmap.
# Objective
CONTRIBUTING.md contains links to pages that are restricted to Bevy Engine Org members.
First time contributors who read CONTRIBUTING.md will end up on a confusing 404 page if they try to follow the link.
Relevant discussion: #4365
## Solution
Replace links with directions to the Triage Team page.
### Note
I'm not sure if `assign themselves as a member` is accurate. I think that is what `automatically request membership` was referring to, but i can't check for myself 😉
Co-authored-by: Carter Anderson <mcanders1@gmail.com>
# Objective
- Update CONTRIBUTING.md with the arrival of a new member who has merge rights
## Solution
- Just add them to the CONTRIBUTING.md
Co-authored-by: Nathan Pinard <42417006+bytemuck@users.noreply.github.com>
[**RENDERED**](https://github.com/alice-i-cecile/bevy/blob/better-contributing/CONTRIBUTING.md)
Improves #910. As discussed in #1309, we'll need to synchronize content between this and the Bevy website in some way (and clean up the .github file perhaps?).
I think doing it as a root-directory file is nicer for discovery, but that's a conversation I'm interested in having.
This document is intended to be helpful to beginners to open source and Bevy, and captures what I've learned about our informal practices and values.
Reviewers: I'm particularly interested in:
- opinions on the items **What we're trying to build**, where I discuss some of the project's high-level values and goals
- more relevant details on the `bevy` subcrates for **Getting oriented**
- useful tricks and best practices that I missed
- better guidance on how to contribute to the Bevy book from @cart <3
