diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 80381417a0..46b11576eb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -432,7 +432,7 @@ Once you've submitted a Pull Request (PR) the various bots will come out and do - checking for commits for their DCO (Developer Certificate of Origin) - kick off the various CI builds -Once these steps are completed, it's just a matter of being patient. As the reviewers have time, they will begin reviewing your PR. When the review process begins, there may be a few layers to this, but the general rule is that you need approval from one of the core maintainers and one from the specific area impacted by your PR. You may also have someone from the community review your changes. This can really help speed things up as they may catch some early items making the review for the maintainers simpler. Once you have the two (2) approvals, it's ready to be merged, a task that is also performed by the maintainers. +Once these steps are completed, it's just a matter of being patient. Reviews are coordinated by maintainers and reviewers based on project area ownership. Prioritization is driven by a number of different factors, but some important ones are size (smaller get higher priority) and alignment with current roadmap priorities. Timely responses to review comments also help keep the pull request moving faster. You may also have someone from the reviewers group review your pull request and request changes. Approval from a member of the reviewers group will greatly increase the priority of your pull request. ### Review Tips diff --git a/LABELS.md b/LABELS.md index f1af06d4fa..fecc115831 100644 --- a/LABELS.md +++ b/LABELS.md @@ -97,6 +97,27 @@ These labels indicate a workflow status for the owners. - `stale` - The issue or pull request has not seen any activity for a while and will be closed if no further activity is seen. - `no stale` - The issue or pull request should not be closed due to inactivity. +## Pull Request Labels + +The following labels indicate the status of a pull request: + +- `status:needs-review` - The pull request needs a review and will be visible in the review queue unless already assigned an owner. +- `status:needs-changes` - Changes have been requested by a reviewer and the pull request will not receive a review until the changes are made. A comment made on the pull request by the author will also push it back into the review queue. +- `status:needs-decision` - The pull request had been marked as more complex and needs a decision from the owners. Progress can still be made and discussion can continue, but expect the review to take longer. These pull requests are often good candidates to bring to a [SIG](https://github.com/backstage/community/tree/main/sigs) meeting. +- `status:awaiting-merge` - The pull request has been approved and is awaiting merge. If you have write access and authored the pull requests you can merge it yourself. If you do not have access to merge and the pull request has not been merged within a day of approval, please notify the assigned reviewer. + +The following labels indicate the size of a pull request: + +- `size:tiny` - Tiny pull requests receive a higher priority for reviews. +- `size:small` - Small pull requests receive a slightly higher priority for reviews. +- `size:medium` - Medium-sized pull request receive no change in priority for reviews. +- `size:large` - Large pull requests receive a slightly lower priority for reviews. +- `size:huge` - Huge pull requests receive a lower priority for reviews. + +The following additional labels also apply to pull requests: + +- `reviewer-approved` - The pull request has been approved by a member of the reviewers group. This pull request receives a much higher priority for reviews. + ## Common Issue Filters This is a collection of common issue filters that can help you find issues that you are looking for or that match your interests and skills. diff --git a/OWNERS.md b/OWNERS.md index 764237d9c1..acf47ce132 100644 --- a/OWNERS.md +++ b/OWNERS.md @@ -19,7 +19,7 @@ These are the separate project areas of Backstage, each with their own project a ### Auth -Team: @backstage/auth-maintainers +Team: @backstage/auth-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Aauth-maintainers) Scope: The Backstage auth plugin and modules, as well as client-side implementations. @@ -34,7 +34,7 @@ Scope: The Backstage auth plugin and modules, as well as client-side implementat ### Catalog -Team: @backstage/catalog-maintainers +Team: @backstage/catalog-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Acatalog-maintainers) Scope: The catalog plugin and catalog model @@ -63,7 +63,7 @@ Scope: Tooling and Community Repo Maintainers for the Backstage [Community Plugi ### Design System -Team: @backstage/design-system-maintainers +Team: @backstage/design-system-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Adesign-system-maintainers) Scope: The Backstage design system, component library, as well as surrounding tooling such as Storybook. @@ -74,7 +74,7 @@ Scope: The Backstage design system, component library, as well as surrounding to ### Documentation -Team: @backstage/documentation-maintainers +Team: @backstage/documentation-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Adocumentation-maintainers) Scope: The Backstage Documentation and Microsite, excluding the plugins listing @@ -86,7 +86,7 @@ Scope: The Backstage Documentation and Microsite, excluding the plugins listing ### Framework -Team: @backstage/framework-maintainers +Team: @backstage/framework-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Aframework-maintainers) Scope: The Backstage core framework, including all revisions of the frontend and backend systems, as well as the App plugin. @@ -113,7 +113,7 @@ Scope: The Backstage [Helm Chart(s)](https://github.com/backstage/charts). ### Home -Team: @backstage/home-maintainers +Team: @backstage/home-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Ahome-maintainers) Scope: The Backstage home page and information architecture @@ -128,7 +128,7 @@ Scope: The Backstage home page and information architecture ### Kubernetes -Team: @backstage/kubernetes-maintainers +Team: @backstage/kubernetes-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Akubernetes-maintainers) Scope: The Kubernetes plugin and the base it provides for other plugins to build upon. @@ -138,7 +138,7 @@ Scope: The Kubernetes plugin and the base it provides for other plugins to build ### Operations -Team: @backstage/operations-maintainers +Team: @backstage/operations-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Aoperations-maintainers) Scope: The management and operation of the main Backstage repository and release process, along with the surrounding tooling. @@ -153,7 +153,7 @@ Scope: The management and operation of the main Backstage repository and release ### Permission Framework -Team: @backstage/permission-maintainers +Team: @backstage/permission-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Apermission-maintainers) Scope: The Permission Framework and plugins integrating with the permission framework @@ -168,7 +168,7 @@ Scope: The Permission Framework and plugins integrating with the permission fram ### Search -Team: @backstage/search-maintainers +Team: @backstage/search-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Asearch-maintainers) Scope: The Backstage Search plugin @@ -180,7 +180,7 @@ Scope: The Backstage Search plugin ### TechDocs -Team: @backstage/techdocs-maintainers +Team: @backstage/techdocs-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Atechdocs-maintainers) Scope: The TechDocs plugin and related tooling @@ -194,7 +194,7 @@ Scope: The TechDocs plugin and related tooling ### Tooling -Team: @backstage/tooling-maintainers +Team: @backstage/tooling-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Atooling-maintainers) Scope: All published Backstage CLI tools in the main `backstage` repository that do not belong to other areas, including `@backstage/cli` and `@backstage/repo-tools`. @@ -214,7 +214,7 @@ These incubating project areas have shared ownership with @backstage/maintainers ### Auditor -Team: @backstage/auditor-maintainers +Team: @backstage/auditor-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Aauditor-maintainers) Scope: The auditor core service, along with auditor usage in the main repository @@ -224,7 +224,7 @@ Scope: The auditor core service, along with auditor usage in the main repository ### Events -Team: @backstage/events-maintainers +Team: @backstage/events-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Aevents-maintainers) Scope: The Events plugin and library, along with events modules in the main repository @@ -234,7 +234,7 @@ Scope: The Events plugin and library, along with events modules in the main repo ### Notifications -Team: @backstage/notifications-maintainers +Team: @backstage/notifications-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Anotifications-maintainers) Scope: The Notifications and Signals plugins and libraries @@ -244,7 +244,7 @@ Scope: The Notifications and Signals plugins and libraries ### OpenAPI Tooling -Team: @backstage/openapi-tooling-maintainers +Team: @backstage/openapi-tooling-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Aopenapi-tooling-maintainers) Scope: Tooling for frontend and backend schema-first OpenAPI development. @@ -254,7 +254,7 @@ Scope: Tooling for frontend and backend schema-first OpenAPI development. ### Scaffolder -Team: @backstage/scaffolder-maintainers +Team: @backstage/scaffolder-maintainers — [Review board](https://github.com/orgs/backstage/projects/14/views/1?filterQuery=no%3Aassignee+label%3Astatus%3Aneeds-review+reviewers%3Ascaffolder-maintainers) Scope: The Scaffolder frontend and backend plugins, and related tooling. diff --git a/REVIEWING.md b/REVIEWING.md index 66af880f43..07fac4c568 100644 --- a/REVIEWING.md +++ b/REVIEWING.md @@ -2,6 +2,36 @@ This file provides pointers for reviewing pull requests. While the main audience are reviewers, this can also be useful if you are contributing to this repository. +## Quick links + +- [Incoming Reviews](https://github.com/orgs/backstage/projects/14/views/1) +- [Personal Reviews](https://github.com/orgs/backstage/projects/14/views/2) +- Project area boards in [OWNERS.md](./OWNERS.md) + +## Review Workflow + +Pull request reviews are coordinated manually by maintainers and reviewers based on project area ownership. Reviews are prioritized and tracked using labels and GitHub Project boards. This review process only applies to the [main Backstage repository](https://github.com/backstage/backstage), other repositories may have their own review processes. + +All incoming pull request reviews are tracked on the [Incoming Reviews board](https://github.com/orgs/backstage/projects/14/views/1). This board can be used by members of the `@backstage/reviewers` group to find pull requests to review, as well as anyone else that wants an overview of all incoming pull requests. + +Project area maintainers can use the same board but with additional filters applied to only show incoming pull requests for their project area. These filtered boards are linked to for each project area in [OWNERS.md](./OWNERS.md). There is also a [personal review board](https://github.com/orgs/backstage/projects/14/views/2) that can be used to track reviews that you have been assigned to. + +There are several labels that help track the status and prioritize pull requests. You can find more information about these labels in [LABELS.md](./LABELS.md#pull-request-labels). + +### Review process for @backstage/reviewers + +Members of the `@backstage/reviewers` do not have any specific areas that they should focus on, they can choose to filter and focus on reviews from any part of the project. They do not assign themselves specific pull requests, but instead leave reviews directly on pull requests without any further process. + +Reviews from this group still have meaningful impact on the review process, as they are picked up by project automation. Approving reviews will add the `reviewer-approved` label to the pull request, which greatly increases its priority and visibility for owners in the area. Likewise, requesting changes will add the `status:needs-changes` label to the pull request, which will remove it from the review queue until the author has commented or made changes. + +### Review process for Project Area Maintainers + +Project area maintainers are responsible for reviewing and ultimately merging or closing pull requests towards their project area. They should use the global or filtered board for their project area to find pull requests to review. When they find a pull request that they want to review, they should assign themselves to the pull request, removing it from the review queue and placing it on their personal review board. + +Once a pull request has been asigned a single owner, it is their responsibility to review and eventually merge or close the pull request. They manage all ongoing requests on their personal review board, typically prioritizing the ones at the top of the board marked with `status:needs-review`. If a pull request is left unreviewed for too long, it will automatically be unassigned and returned to the review queue. Once a pull request has been approved by the assigned owner, the owner should merge the pull request themselves if it is an outside contribution, but otherwise generally leave that to the author of the PR. + +Some pull requests may require review from multiple project areas. In these cases the most relevant owner should assign themselves and coordinate with the other owners for additional reviews. If the most relevant owner is not clear, this is preferrably solved in a discussion among the owners. Frequent conflicts should lead to a discussion whether `CODEOWNERS` should be updated to simplify the review process. If some owners are currently unavailable, other owners can assign themselves to the pull request and bring it to the point where they approve the changes for their area, and then send the pull request back to the review queue. + ## Code Style See our code style documented at [STYLE.md](./STYLE.md).