# Bevy Project Goals

## What are we doing?

- We are introducing the concept of public-facing "Bevy Project Goals". Project Goals are work that is impactful, controversial, high-effort, or complicated.
- Bevy's existing Working Group system now ties into Project Goals. Every Working Group has a Goal.
- We are introducing a new standardized process for SMEs (Subject Matter Experts) in each area to manage incoming pull requests and issues, and propose new project goals. This will be done using new area-specific Github Projects, managed by the **SMEs** of each area.
- We are introducing a new "Bevy Project Goals" Github Project, managed by Bevy's **SMEs** and **Project Lead**. This provides a high level view into our current priorities, and what is currently being worked on.

## Why are we doing this?

- Enable defining project goals and giving them priority over other work
- Quick yes/no/later feedback for feature proposals as early as possible
- Big efforts move forward when they are staffed by SMEs
- Big efforts do _not_ move forward when they are not staffed by SMEs. Avoid people building things we aren't ready for or don't want. Bevy is understaffed from a project leadership perspective and we need a system that allows us to priortize our efforts.
- Improve responsiveness from project leaders
- Improve trust in the development process
- Improve visibility into project goals and priorities. Many people ask for a "roadmap". We aren't planning things out linearly in that way, but this serves a similar purpose.
- Make it easier for interested developers to find "project aligned" work
- Standardized project management process across areas
- Remove some redundancies and manual labor in our project management workflows

## The Pieces

- **Area**: A design space
- ECS, Rendering, Assets, UI, Scenes, etc
- **Goal**: Something impactful, likely controversial, high-effort, or complicated, that we want to accomplish in an **Area**
- In general, nobody should be making large or controversial changes to the engine without an active, approved **Goal**.
- **Goals** inherently require _collaboration_ to bring them to completion. They are never the work of a single individual. At the very least, there is someone coming up with a design, and one or more **SME** verifying the design.
- **Goals** have a short, functional name, as it would be communicated to the public (not the "fun" working group names we are currently using). This is a market-able "feature name", like "PBR Renderer", "Relationships", etc. Avoid using things like "initial" or "MVP" in the name, as this is implied.
- **Goals** can be large, but they need a defined completion criteria. For something large like a "Bevy Editor" **Goal**, consider breaking it into smaller pieces (ex: Editor UI Widgets, Core Editor App Framework, Scene Editor, Editor Inspector, etc).
- **Goals** define a high level feature or need, not low level implementation details. Implementation details are determined by the **Working Group** and approved by **SMEs**
- **Goals** can be "staffed" by one or more **SME**. Staffing a **Goal** means (1) the **SME** believes the **Goal** should completed (2) the SME is willing to spend time guiding the vision and implementation (3) the **SME** believes they have the competency required to be a good shepherd of the **Goal**.
- If an appropriate **SME** is unavailable, **Maintainers** can also choose to staff a **Goal**, provided relevant **SMEs** and **Project Leads** are on board.
- **SMEs** should "assign" themselves to goals on github that they are staffing.
- Goals have a tracking issue (created by **SMEs**) with the `C-Goal` label. This should use Github sub-issues, not a markdown checklist. Anyone with triage permissions can add sub-issues.
- Statuses (Github Project "column" names):
- Proposed: One or more **SME** thinks this is worth considering as a goal
- Postponed: We might want to do this later.
- Blocked (Approved): We want to do this, one or more SME has agreed to staff it, and the Project Lead has approved it, but other work is blocking it
- If a Goal is blocked by other issues (including other Goals), they should be referenced in the Goal's description.
- Inactive (Approved): we want to do this, one or more **SME** has agreed to staff it, the **Project Lead** has approved it, but there is no active **Working Group**.
- Active (Approved): a **Working Group** is actively working toward this, with one or more active **SME** staffing it.
- Done: The goal's issue has been closed (this is set automatically by a Github Project Workflow)
- Declined: Closed as "not planned"
- Completed: Closed as "completed"
- **Triage Team**: Categorizes and labels Issues and PRs
- Can label issues as controversial, but must defer to **SMEs** if they think differently
- Cannot define **Goals** or use the C-Goal label
- **SME**: Governs an **Area**
- Blesses controversial issues or pull requests via votes
- Provides definitive answers as to whether work in an **Area** is controversial, or requires a **Goal**
- Proposes **Goals** in their **Area**
- "Staffs" **Goals** in their **Area**
- As a rule of thumb, an **SME** should only staff 1-3 **Goals** at a time, across all **Areas**
- Manages **Area Project** on GitHub
- **Project Lead**: Governs all **Areas** (by default)
- Considered to be an **SME** in every **Area** (by default)
- Has final say on **Goal** approval. Every **Goal** is considered by the **Project Lead** before entering the Approved / Postponed / Denied states.
- The same "staffing" rule of thumb applies: A **Project Lead** should only staff 1-3 **Goals** at a time, across all **Areas**.
- Will review all **Area Projects**, and the **Project Goals** on a weekly basis.
- **Area Project**: A place where work is organized, prioritized, and blessed by SMEs
- Only editable by **SMEs** and **Maintainers**
- Maintainers should let **SMEs** manage the board in general.
- Auto-adds issues and prs to the project based on Area Label via a Project Workflow
- Standardized "baseline" Github Project views and statuses
- **SMEs** can add more if they would like, provided the main tabs are unchanged, first in the tab order, and the process defined here is adhered to.
- Prefer Labels and Github Project Tables, not Project Boards and Statuses
- Board Statuses generally introduce redundancies with Labels
- Labels are easily queryable, and have high visibility
- Boards hide Labels from view, obscuring important information
- By being Label-driven we can have a single source of truth
- **SMEs** will regularly "triage" incoming issues and PRs
- **Maintainers** can pick up the slack here if things are moving slowly, but this should be considered a "problem to be solved". **Areas** need active **SMEs**, and if **Maintainers** are stepping in, that implies inactivity.
- Issues, PRs, and Goals should be _prioritized_ in "All" table in the Github Project. Higher on the board == higher priority. Exactness is unnecessary, and significant labor should not be expended to produce an ordering. But **SMEs** should try their best to give precedence to the things that need it / prevent them from getting buried in the noise. **SMEs** can (and should) do this individually, but when in doubt (and it seems important), it should be discussed.
- Project Tabs (Views)
- Triage (List grouped by Needs Triage and Triaged)
- This is where SMEs "see" incoming PRs and assign labels that are their responsibility. The process is:
- Understand the issue. Rename / Reframe / dedupe it as necessary.
- Apply the following labels, where relevant
- C-Needs-Goal (something would be a part of a larger goal, and should not be continued until that goal is created and staffed). C-Needs-Goal items should generally either be closed after the Goal is created, or added as sub-issues to the Goal.
- X-Controversial (There is active debate or serious implications around merging this PR, requiring an SME to resolve the controversy)
- I propose we rename this to X-Needs-SME to be more "functional" and self-descriptive
- P-High for anything that is an immediate, pressing concern
- Change status to Triaged, prioritize relative to other items in the "All" board
- All (List of `A-AREA -status: Done`, manual ordering, grouped by Status)
- PRs (List of `A-AREA is:pr -status: Done`, manual ordering)
- Issues (List of `A-AREA is:issue -status: Done`, manual ordering)
- Goals (List of `A-AREA C-Goal state:open`, manual ordering)
- Statuses (Github Project "column" names):
- Needs Triage: SMEs have not triaged this yet
- Triaged: SMEs have triaged this
- Done: this item has been closed
- **Working Group**: A group of people trying to accomplish a **Goal**
- Anyone can participate
- Always more than one person.
- Always staffed by at least one **SME**.
- Named after the **Goal**, for easy discovery and correlation
- The **Working Group** will come up with proposals (written designs, pull requests), which the **SMEs** in the **Area** will approve or deny (via votes)
- If (and only if) a **Goal** has an active **Working Group**, the **Goal** is considered active.
- **Working Group** members can collaborate on the Bevy Discord via an official **Working Group** thread (named after the **Goal**)
- The **Goal** issue should link to the Discord Working Group thread.
- **Project Goals**: A Github Project providing a consolidated public view into the project's **Goals**
- Project States: the states of **Goal** (see above)
- This breaks the "labels over project states" rule established in the **Area Project** section, in the interest of providing a nice public-facing view.
- Views:
- Board: the "main" view, showing all of the **Goal** states
- List: provides additional details at a glance, such as assignees
- Completed Goals (a list view of `is:closed closed_reason:Completed label:C-Goal`)
- See what we have achieved!
- Denied Goals: (a list view of `is:closed label:C-Goal closed_reason: Not Planned`)
- A list of "non goals", which people can learn from and refer to.
- **Project Lead** will review this weekly and work with **SMEs** to approve/postpone/deny **Goals**
- **Lifecycle of a Goal**
- Someone proposes a feature in the form of an issue
- Triage Team assigns it to an **Area**
- [Github Project Workflow](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations) adds it to the **Area Project**
- **SMEs** identify that the issue needs a goal and apply the C-Needs-Goal label
- **SMEs** discuss the framing of the Goal and create a new issue with the C-Goal label.
- A Github Project Workflow picks up the C-Goal issue and adds it to the **Project Goals** board in the Proposed state.
- **Project Lead** and **SMEs** discuss how to handle the **Goal**: Deny, Inactive (Approved), or Postpone. Approval is contingent on an **SME** agreeing to staff it, and put energy into helping the Working Group bring it to completion.
- If the **Goal** is Inactive (Approved), and there is enough commitment and support from the community to form a **Working Group**, it moves into the Active (Approved) state.
- The **Project Lead** adjusts the priorities of the **Goals** (expressed via Project Board order), based on the needs of the project.
- When a **Goal** is completed, the issue is closed out. A Github Project Workflow moves it into the Done status.
- **FAQ**
- "What is the difference between X-Controversial and C-Goal?"
- C-Goal is inherently X-Controversial, but not all X-Controversial work is C-Goal
- In general, C-Goal is a measure of investment, risk, and publicity. If SMEs cannot resolve the work with a very short time investment and low risk, or the work is an ongoing thing, it is almost certainly a C-Goal. If it has significant implications for public reception or has significant public interest, it is a C-Goal.
- When in doubt, it is probably a Goal.
- Is the work a part of a larger whole? If yes, that "whole" probably needs a **Goal**
- Does the work require a long iterative development process? If yes, it probably needs a **Goal**
- Would the work benefit from collaboration and consensus building? If yes, it probably needs a **Goal**
- Does the work have significant implications for Bevy's user experience or internals? If so, it probably needs a **Goal**
- "Does **Goal**-like work that already has a PR require a **Goal**?"
- In general, the answer is yes
- If the PR is the work of a single person, then _yes_
- If the PR is not self-contained (ex: more work is required after), then almost certainly _yes_
- If the PR had no input from SMEs or Project Leads, and will require significant effort to review and iterate, then _yes_.

## GitHub Projects

To illustrate what this proposal looks like in practice, I've put together the proposed GitHub Projects

- [Bevy Project Goals](https://github.com/orgs/bevyengine/projects/23/views/1)
- [Area Project Template](https://github.com/orgs/bevyengine/projects/24/views/1)

I also instantiated the Area Project Template for the Rendering area (and manually populated it with some Issues and PRs) to illustrate its use in practice. This is not yet used for "real" things. Consider it a "demo":

- [Demo A-Rendering Project](https://github.com/orgs/bevyengine/projects/25/views/1)

## Todo
- [x] Iterate on the proposal with Maintainers
- [x] Propose to SMEs
- [ ] Propose publicly
- [ ] Update Contributing Guide
- [ ] Port existing Working Groups to the Goals system
- [ ] Create C-Goal issues (or label suitable existing issues with C-Goal)
- [ ] Rename working groups to functional, public facing names
- [ ] Update existing processes
- [ ] Remove "Type" custom field on boards. Re-sorting things into Bug vs Improvments via a custom type (ex: the Audio board) is too laborious. Use filtered List views + labels for C-Bug vs C-Feature instead. (ex: a C-Bug list view tab)
- [ ] Remove all redundant project states
- Anything redundant with a Label can be seen in the Labels section of the List view. Custom views that filter by label can also be used.
- [ ] Redundancies
- [ ] Needs Adoption (S-Adopt-Me)
- [ ] Controversial (X-Controversial)
- [ ] Needs rebase - already encoded in the PR ... does it have merge conflicts y/n
- [ ] Can easily become out of sync, requires vigilance to keep updated
- [ ] Needs update (S-Blocked)
- [ ] Blocked (S-Blocked)
- [ ] Awaiting Final Review (S-Ready-Final-Review)
- [ ] Announce publicly via blog post

## Related Work

These things are related, but should be discussed separately on their own time.

- Expand our SMEs
- Rename / reframe some existing labels
- `S-Needs-SME` to `S-Waiting-for-SME`
- `S-Waiting-for-SME` is the _temporary_ label indicating that an `X-Needs-SME` issue/pr _currently_ doesn't have enough input from SMEs. This name has parity with the already-in-use `S-Waiting-for-Author`.
- `X-Controversial` to `X-Needs-SME`
- `X-Needs-SME` is more functional and self descriptive
- This serves as the (usually permanent) label that an issue/pr is of the _type_ that needs SME voting / attention.
- Clean up Issues / PRs / Backlog
- Clean up old processes and systems
- Reframe (and/or Deprecate) RFCs
- Working Groups _should_ in general produce design documents. But there is a general agreement that the current RFC process is "too stuffy" (as evidenced by the general lack of participation, both from the community and project leadership). Our semi-official "HackMD culture" has been much more successful. But it is also quite disconnected from Github (potentially different accounts / usernames, linking and cross-linking between Github and HackMD is harder / less friendly, HackMD is generally less discoverable), reviews / comments are frustratingly limited and hard to manage, HackMD is centralized / not git-driven, etc. I believe a "less stuffy" GitHub-driven workflow might be the better approach. Ex: a "design documents" repo with _optional_ PRs and generous merge rights. We could even have another "book" on the website built from that markdown.
- The alternative is to fully endorse / require HackMD for design documents, and boost its visibility.
- Remove unused / nonstandard project boards