Add documentation for Safe-Merge-Queue

Safe-Merge-Queue is undocumented! This also updates existing documentation for Unsafe-Merge-Queue and Merge-Queue.

* docs/Deep Dive/GitHub/Merging.md
* docs/Deep Dive/GitHub/PullRequests.md
* docs/Getting Started/ContributingCode.md

Author: briannafan

docs/Deep Dive/GitHub/Merging.md

@@ -1,6 +1,6 @@
 # Merging
 
-This page explains the proper way to set test expectations, as well as highlights the differences between `merge-queue` and `unsafe-merge-queue`. There will also be a section that gives tips on what to do when you need to edit an existing pull-request, and how to cleanly re-submit that.  
+This page explains the proper way to set test expectations, as well as highlights the differences between `safe-merge-queue`, `merge-queue`, and `unsafe-merge-queue`. There will also be a section that gives tips on what to do when you need to edit an existing pull-request, and how to cleanly re-submit that.
 
 ## Test Gardening
 Since direct commit access is limited only to repository administers, this will change the prior workflow of Test Gardening/Setting test expectations. As such the new process is outlined as follows: 
@@ -22,12 +22,11 @@ An example template for your commit message looks like:
 
 6. After adding the `unsafe-merge-queue` label, your pull-request will attempt to be committed. This should take 1-3 minutes, and should commit without issue given that you followed the steps above. If there is an issue with your pull-request then the commit will fail with an error.
 
+## Safe-Merge-Queue
+`Safe-Merge-Queue` is a great way to verify that all builds and tests succeed and land the pull request without manual intervention. `Safe-Merge-Queue` checks the status of pull requests with the label every 15 minutes. Once all EWS tests pass, `Safe-Merge-Queue` will automatically land your pull request for you.
+
 ## Merge-Queue
-The merge-queue is used in conjunction with `Tools/Scripts/git-webkit land`. When a pull-request goes through merge-queue it will build and test it. After you have pushed your pull-request to [WebKit Pull Requests](https://github.com/WebKit/WebKit/pulls), if you manually add the `Merge-Queue` label it will build and run your commit, or 'patch' if you prefer, against EWS to determine if you commit has any stylistic issues, or if your commit unexpectedly breaks things. `Merge-Queue` is going to be the label you will want to use if you need your pull-request to go through testing. Once testing is completed, and if s reviewer has approved your pull-request, the `Merge-Queue` will automatically land your pull-request for you.  
+The `Merge-Queue` is used in conjunction with `Tools/Scripts/git-webkit land`. When a pull-request goes through merge-queue it will build and test it. After you have pushed your pull-request to [WebKit Pull Requests](https://github.com/WebKit/WebKit/pulls), if you manually add the `Merge-Queue` label, EWS will determine if your commit has any stylistic issues and if your commit builds on macOS and passes WK2 layout tests. You should use `Merge-Queue` if you want your pull-request to go through these tests before landing. Once testing is completed, and if a reviewer has approved your pull-request, the `Merge-Queue` will automatically land your pull-request for you.
 
 ## Unsafe-Merge-Queue
-`Unsafe-Merge-Queue` effectively replaces `svn dcommit` since directly committing to the repository is now only available to repository administers. When using `Unsafe-Merge-Queue` a style check will be run on your pull-request, and then it will attempt to commit the pull-request without building it or testing it. As long as there are no stylistic, or formatting issues `Unsafe-Merge-Queue` will commit your change in approx. 1-3 minutes. `Unsafe-Merge-Queue` should **ONLY** be used for very simple, basic changes that can't really break anything too badly, or setting expectations for tests. 
-
-## Editing existing pull-requests
-information to be published at a future date. 
-
+When using `Unsafe-Merge-Queue` a style check will be run on your pull-request, and then it will attempt to commit the pull-request without building it or testing it. As long as there are no stylistic or formatting issues, `Unsafe-Merge-Queue` will commit your change in approx. 1-3 minutes. `Unsafe-Merge-Queue` should **ONLY** be used for very simple, basic changes that can't really break anything too badly, or setting expectations for tests.

docs/Deep Dive/GitHub/PullRequests.md

@@ -28,12 +28,12 @@ In addition to pull request commits having verbose commit messages, the WebKit p
 
 ## Reviewing
 
-Commits generally require the approval of a [reviewer](https://webkit.org/team/#reviewers), although there are narrow exceptions for test expectation gardening and build fixes. Reviewers will approve pull requests through the GitHub UI by marking pull requests as "Approved." Note that approval from someone who is not a reviewer will not be recognized by [Merge-Queue](/Getting Started/ContributingCode#merge-queue).
+Commits generally require the approval of a [reviewer](https://webkit.org/team/#reviewers), although there are narrow exceptions for test expectation gardening and build fixes. Reviewers will approve pull requests through the GitHub UI by marking pull requests as "Approved." Note that approval from someone who is not a reviewer will not be recognized by the [Merge-Queues](/Getting Started/ContributingCode#merge-queues).
 
 ## Landing
 
-Only repository administers have direct commit access, and this is reserved for repairing infrastructure issues. Pull requests should be landed through [Merge-Queue](/Getting Started/ContributingCode#merge-queue), which is achieved by applying [`merge-queue`](https://github.com/WebKit/WebKit/labels?q=merge-queue) or [`unsafe-merge-queue`](https://github.com/WebKit/WebKit/labels?q=unfsafe-merge-queue) label to your pull request.
+Only repository administrators have direct commit access, and this is reserved for repairing infrastructure issues. Pull requests should be landed through the [Merge-Queues](/Getting Started/ContributingCode#merge-queues), which is achieved by applying [`safe-merge-queue`](https://github.com/WebKit/WebKit/labels?q=safe-merge-queue), [`merge-queue`](https://github.com/WebKit/WebKit/labels?q=merge-queue), or [`unsafe-merge-queue`](https://github.com/WebKit/WebKit/labels?q=unfsafe-merge-queue) label to your pull request.
 
-[Merge-Queue](/Getting Started/ContributingCode#merge-queue) will check to make sure a change is reviewed by adding the name of all [reviewers](https://webkit.org/team/#reviewers) who have approved a pull request to the commit message. [Merge-Queue](/Getting Started/ContributingCode#merge-queue) will then check the commit message for `Reviewed by`.
+Each queue makes sure a change is reviewed by adding the name of all [reviewers](https://webkit.org/team/#reviewers) who have approved a pull request to the commit message. It will then check the commit message for `Reviewed by`.
 
-Note that [Merge-Queue](/Getting Started/ContributingCode#merge-queue) will reject pull requests that are labeled by contributors who are not [committers](https://webkit.org/team/#committers).
+Note that the Merge-Queues will reject pull requests labeled by contributors who are not [committers](https://webkit.org/team/#committers).

docs/Getting Started/ContributingCode.md

@@ -54,13 +54,17 @@ git webkit pr
 
 ## Landing Changes
 
-### Merge-Queue
+### Merge Queues
 
-To land a pull request, add the [`merge-queue`](https://github.com/WebKit/WebKit/labels?q=merge-queue) or [`unsafe-merge-queue`](https://github.com/WebKit/WebKit/labels?q=unfsafe-merge-queue) label to your pull request. These labels will put your pull request into the [Merge-Queue](https://ews-build.webkit.org/#/builders/74) and [Unsafe-Merge-Queue](https://ews-build.webkit.org/#/builders/75), respectively, which will commit your pull request to the WebKit repository
+To land a pull request, add the [`safe-merge-queue`](https://github.com/WebKit/WebKit/labels?q=safe-merge-queue), [`merge-queue`](https://github.com/WebKit/WebKit/labels?q=merge-queue), or [`unsafe-merge-queue`](https://github.com/WebKit/WebKit/labels?q=unsafe-merge-queue) label to your pull request. These labels will put your pull request into [Safe-Merge-Queue](https://ews-build.webkit.org/#/builders/Safe-Merge-Queue), [Merge-Queue](https://ews-build.webkit.org/#/builders/Merge-Queue), and [Unsafe-Merge-Queue](https://ews-build.webkit.org/#/builders/Unsafe-Merge-Queue), respectively, which will commit your pull request to the WebKit repository.
 
-[Unsafe-Merge-Queue](https://ews-build.webkit.org/#/builders/75) inserts reviewer information into a commit's message and modified change logs. We then check to ensure that a pull request has been reviewed by checking the commit message before landing the change. [Unsafe-Merge-Queue](https://ews-build.webkit.org/#/builders/75) _does not_ validate that a pull request builds.
+Each queue runs a style-check and inserts reviewer information into the commit message and modified change logs. They check that a pull request has been reviewed by checking the commit message before landing the change.
 
-Along with the actions performed by [Unsafe-Merge-Queue](https://ews-build.webkit.org/#/builders/75), [Merge-Queue](https://ews-build.webkit.org/#/builders/74) will validate that a pull request builds and run layout tests before landing the change.
+[Safe-Merge-Queue](https://ews-build.webkit.org/#/builders/Safe-Merge-Queue) checks the status of pull requests with the label every 15 minutes. Once all EWS tests pass, the pull request is automatically landed. If a test fails, the pull request is labelled with merging-blocked.
+
+[Merge-Queue](https://ews-build.webkit.org/#/builders/Merge-Queue) validates that a pull request builds on macOS and runs WK2 layout tests before landing the change.
+
+[Unsafe-Merge-Queue](https://ews-build.webkit.org/#/builders/Unsafe-Merge-Queue) does not perform any additional validation and should only be used for changes that have minimal impact (e.g. setting test expectations, adding to contributors.json) or changes that need to be landed quickly (e.g. build fix or revert).
 
 ### git-webkit land