"Contributor's Guide" Design Proposal

# "Contributor's Guide" Working Group This is the design document for Bevy's "Contributors Guide" working group, outlining the scope of the project as well as concrete plans for its implementation. The main motivations for this project are described in [issue #1146](https://github.com/bevyengine/bevy-website/issues/1146). ## Scope and process Our goal is to integrate useful information from a variety of sources into a new online "Contributor's Guide" as part of the Bevy website. This includes some reorganization, but otherwise we will minimize changes to the existing documents as much as possible. When editing or introducing new content, we will focus on ease-of-use and clarity for ESL (English as a Second Language) users. ### Phase 1 - Setup The very first step is to setup the guide on [bevyengine/bevy-website]. A new folder will be created at `content/contributing` and accessible from <https://bevyengine.org/contributing>. This folder will follow the same style as the [Bevy Book], with a navigation bar on the left and tabs on the bottom to go to the next and previous page. See [`_index.md`] for the template. Remember to add it to public draft; that way it isn't discoverable by search engines before it is polished or done. [bevyengine/bevy-website]: https://github.com/bevyengine/bevy-website [Bevy Book]: https://bevyengine.org/learn/book/getting-started/why-bevy/ [`_index.md`]: https://github.com/bevyengine/bevy-website/blob/6fd5194bd7548fecf05c59ebd4ebf1f8dda43377/content/learn/book/_index.md ### Phase 2 - Tutorials and Copying With the infrastructure set up, the next step is to write the tutorials and copy existing documentation! There will be multiple sections with individual pages each, assigned to different participants of the working group. To speed up the drafting process, each section will live in a separate HackMD document.  1. Introduction - Nth/Anyone 1. A friendly introduction to the project. 2. Move [What we're trying to build]. 3. Move [Getting Oriented]. 4. Move [Contributing To Bevy]. [Contributing To Bevy]: https://github.com/bevyengine/bevy/blob/main/CONTRIBUTING.md#contributing-to-bevy [Getting Oriented]: https://github.com/bevyengine/bevy/blob/main/CONTRIBUTING.md#getting-oriented [What we're trying to build]: https://github.com/bevyengine/bevy/blob/main/CONTRIBUTING.md#what-were-trying-to-build. 2. How You Can Help - Nth/Anyone - An overview of different ways to contribute to the project. - Move [Making Changes To Bevy]. This section is valuable but could perhaps be merged with other content. - Move [How you can help]. This section is excellent but long. We should try to break some of this information up and present it elsewhere. [Making Changes To Bevy]: https://github.com/bevyengine/bevy/blob/main/CONTRIBUTING.md#making-changes-to-bevy [How You Can Help]: https://github.com/bevyengine/bevy/blob/main/CONTRIBUTING.md#how-you-can-help 3. [Using Github Issues] - BD103 - Explains how issues should be filed and used to manage work. - Move [Classifying PRs]. - Move [Prioritizing PRs and issues] - Move [Closing PRs and Issues]. [Using Github Issues]: https://hackmd.io/@BD103/ryPyPr8MA [Classifying PRs]: https://github.com/bevyengine/bevy/blob/main/CONTRIBUTING.md#classifying-prs [Prioritizing PRs and issues]: https://github.com/bevyengine/bevy/blob/main/CONTRIBUTING.md#prioritizing-prs-and-issues [Closing PRs and Issues]: https://github.com/bevyengine/bevy/blob/main/CONTRIBUTING.md#closing-prs-and-issues 4. Your First Pull Request - BD103 - This is a tutorial that walks through implementing a small piece of code. It should be beginner friendly, making no assumptions about the skills and prior experiences of the reader. - Topics include: - Installing Rust, Git, an editor (VSCode?), and signing up for Github. - Prefer linking to external documentation here when possible. - Finding an issue to solve, preferably labeled with `D-Trivial` or `D-Straightforward`. - Forking Bevy and checking out the code locally. - Making a new branch and committing changes. - Lint code using the `ci` tool. - Creating a pull request, with an example description. - Responding to reviews. - Merging the PR (mention the 2 reviewer requirement) and final thoughts. - These pages do not need to be long articles. They can be short and succint, making it easier to digest for newcomers. 5. [Your First Review] / Reviewing Pull Requests - ramirezmike/Anyone - A new section including a new tutorial (similar size/complexity/audience as "Your First Pull Request" tutorial) which explains the importance of review, and how to be helpful and productive as a reviewer. - Topics include: - Who can review? (Everyone) - How to review a pull request. - The importance of review to the project. - How do identify and mark different types of feedback (nit/blocking). - Dealing with conflicting ideas and consensus. [Your First Review]: https://hackmd.io/@nth/contributors_guide_book_view/https%3A%2F%2Fhackmd.io%2F%40ramirezmike%2FB1clX_UzR 6. Additional Sections - These can either just be top-level pages organized according to the existing documents, or sorted under sections by their relevant domain. (e.g. Bevy Website, Bevy, Repository-Agnostic) - A chapter on the organization can be added here, based on [`the_bevy_organization.md`]. Or this could be merged into the [Bevy People] page. - A chapter on style guides and [linters]. Both the [Engine Style Guide] and the [Examples Style Guide] should be integrated. - Other parts of [How You Can Help] can be broken out into their own sections. - A section on contributing on the website can be ported from [`bevy_website/CONTRIBUTING.md`]. - The [Release Checklist] along with the procedure for release-candidates. [`the_bevy_organization.md`]: https://github.com/bevyengine/bevy/blob/ec418aa429142972032f56a43ab963bd3be766d4/docs/the_bevy_organization.md [Bevy People]: https://bevyengine.org/community/people/ [linters]: https://github.com/bevyengine/bevy/blob/main/docs/linters.md [Engine Style Guide]: https://github.com/bevyengine/bevy/blob/main/.github/contributing/engine_style_guide.md [Examples Style Guide]: https://github.com/bevyengine/bevy/blob/main/.github/contributing/example_style_guide.md [`bevy_website/CONTRIBUTING.md`]: https://github.com/bevyengine/bevy-website/blob/main/CONTRIBUTING.md [Release Checklist]: https://github.com/bevyengine/bevy/blob/main/docs/release_checklist.md ### Phase 3 - Editing and Revision Now that the basic content has been added onto the foundation, we should proof-read what we have, revise it where need be, and identify gaps in knowledge; places where it'd be useful to have information, but at present it is lacking. Sections will remain in HackMD during revision. We will open a PR on the website for each section as they are approved by the working group. - During the proof-reading process the main things to look out for are poor grammar, and wrong or outdated info. These will be revised on a per-page basis. - Critical knowledge gaps will be fixed immediately, while "good to have" ones will be postponed until Phase 5. - Places where too much information is condensed into a single page will be split up, such as for `CONTRIBUTING.md`. - Any further shortfallings that do not involve writing new, nonessential content will be fixed at this point. ### Phase 4 - Publishing At this point, the Contributor's Guide is written and refined to a quality we feel okay publishing for the layman and average user seeing. The guide does not need to be *complete*, but it should contain all pre-existing information. - The Contributor's Guide will need to be removed from public draft so that it is discoverable and visible. - A link titled Contributing should be added in the navigation header beside the Foundation link. - All the old resources, such as the [`docs`] folder, should be removed and [`CONTRIBUTING.md`] should be updated to point towards the Contributor's Guide. [`docs`]: https://github.com/bevyengine/bevy/tree/ec418aa429142972032f56a43ab963bd3be766d4/docs [`CONTRIBUTING.md`]: https://github.com/bevyengine/bevy/blob/ec418aa429142972032f56a43ab963bd3be766d4/CONTRIBUTING.md ### Phase 5 - New Content The Contributor's Guide has already been published at this point, but there are still a few missing topics that would benefit it. In this phase, individual pages and sections will be written to fill additional gaps. We will make a list of these sections at the start of this phase. Each new section will live in a new HackMD document during drafting and editing. When we are happy with a section, we will open a website PR. Some ideas include: - Profiling Bevy - Logs, tracing, and tracey - Build timings - The unstable developer docs (<https://dev-docs.bevyengine.org>) - Reading CI errors - Tips and tricks for PR authors - Keep changes small and easy to review, splitting up when necessary. - Updating from main using merge or rebase. (And the differences between the two.) - Finding issues to work on. (Finding your niche.) - Tips and tricks for reviewers - Use `gh co <NUMBER>` to checkout a pull request's code. - Sorting PRs by label. - `S-Ready-For-Final-Review` - Working together on Discord - Github Milestones, Bevy release train, and release-candidates - Working through controversial changes, project lead / maintainer / SME blessing - Testing 3rd party plugins on main using patching - [Overriding Dependencies](https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html) - Updating dependencies - Reading through release notes and handling breaking changes - Preventing dependency duplication