diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 4f238a922c7..1c7091477e8 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -16,7 +16,7 @@ There are multiple ways to contribute to the web-features repository, such as: * Adding a missing feature to the repository, from scratch. * Adding a missing feature to the repository, by updating a feature that was already drafted. * Updating an existing feature, for example to change its name, description, support data, or other fields. -* Reviewing a pull request that was submitted by someone else, to check if the feature is correctly authored. +* [Reviewing a pull request](./reviewing.md) that was submitted by someone else, to check if the feature is correctly authored. In any case, **thank you** for wanting to help. This document will guide you through the process of contributing to the web-features repository. diff --git a/docs/README.md b/docs/README.md index 53f1d9b3029..cc99dd7733f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,4 +2,5 @@ * To learn to contribute to the web-features project, see [Contributing to the web-features project](./CONTRIBUTING.md). * For guidelines on writing features, see [Feature guidelines](./guidelines.md). +* For guidelines on reviewing and merging changes, see [Pull request and issue management](./reviewing.md). * For information about what Baseline is and how Baseline status is calculated, see [Baseline](./baseline.md). diff --git a/docs/reviewing.md b/docs/reviewing.md new file mode 100644 index 00000000000..3fe8e255bcd --- /dev/null +++ b/docs/reviewing.md @@ -0,0 +1,36 @@ +# Pull request and issue management + +## Merging pull requests + +> [!NOTE] +> This information is for [project peers and owners](../GOVERNANCE.md#roles-and-responsibilities). + +If a pull request has been approved and tests are passing, then you can merge it. +Follow these steps to merge: + +1. Make sure you **should** merge this pull request. + In general, only merge pull requests you are already familiar with, either as an author or reviewer. + +1. Make sure **you** should merge this pull request. + Some changes—most notably, feature removals, tooling and policy changes, and schema changes—require an owner to merge. + See [the privileges and responsibilities matrix](../GOVERNANCE.md#privileges-and-responsibilities-matrix) for more information. + +1. Make sure there are no explicit blockers to merging. + Blockers include: + + - The pull request has the [blocked label](https://github.com/web-platform-dx/web-features/pulls?q=is%3Aopen+is%3Apr+label%3Ablocked). + - A reviewer asked to re-review before merging or has requested changes that have not been addressed with a commit or comment. + - The author explicitly asked to delay merging. + - The author explicitly asked for review from all requested reviewers (the presumption is at least one but not all). + + If a blocker no longer applies, remove the label or [dismiss the stale review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/dismissing-a-pull-request-review). + +1. If the pull request might require a Semantic Versioning MAJOR or MINOR release, then add the [minor version required](https://github.com/web-platform-dx/web-features/labels/minor%20version%20required) or [major version required](https://github.com/web-platform-dx/web-features/labels/major%20version%20required) label. + +1. Click the **Squash and merge** button, then prepare the commit message. + + Clean up the subject and message fields so they make sense as a single unit. + For example, delete boilerplate messages about applying changes from code review. + Often an imperative-noun subject, such as "Add example feature", is sufficient. + +1. When you're ready to commit the changes, click **Confirm squash and merge**.