docs: update docs to reflect new PR targeting methods for release trains (angular#38401)

josephperrott · josephperrott · commit e8ea839df804 · 2020-08-27T14:52:04.000-07:00
As part of the migration to a common strategy/method for branching and releasing across the main angular repositories, updates need to be made to the documentation. These changes reflect the updates made and is based on the following document which describes the merging label expectations: https://docs.google.com/document/d/197kVillDwx-RZtSVOBtPb4BBIAw0E9RT3q3v6DZkykU PR Close angular#38401
diff --git a/docs/CARETAKER.md b/docs/CARETAKER.md
@@ -4,71 +4,23 @@ Caretaker is responsible for merging PRs into the individual branches and intern
 
 ## Responsibilities
 
-- Draining the queue of PRs ready to be merged. (PRs with [`PR action: merge`](https://github.com/angular/angular/pulls?q=is%3Aopen+is%3Apr+label%3A%22PR+action%3A+merge%22) label)
+- Draining the queue of PRs ready to be merged. (PRs with [`action: merge`](https://github.com/angular/angular/pulls?q=is%3Aopen+is%3Apr+label%3A%22action%3A+merge%22) label)
 - Assigning [new issues](https://github.com/angular/angular/issues?q=is%3Aopen+is%3Aissue+no%3Alabel) to individual component authors.
 
 ## Merging the PR
 
-A PR needs to have `PR action: merge` and `PR target: *` labels to be considered
-ready to merge. Merging is performed by running `merge-pr` with a PR number to merge.
+A PR needs to have `action: merge` and `target: *` labels to be considered
+ready to merge. Merging is performed by running `ng-dev pr merge` with a PR number to merge.
+
+The tooling automatically verifies the given PR is ready for merge. If the PR passes the tests, the
+tool will automatically merge it based on the applied target label.
 
 To merge a PR run:
 
 ```
-$ ./scripts/github/merge-pr 1234
+$ yarn ng-dev pr merge <pr number>
 ```
 
-The `merge-pr` script will:
-- Ensure that all appropriate labels are on the PR.
-- Fetches the latest PR code from the `angular/angular` repo.
-- It will `cherry-pick` all of the SHAs from the PR into the current corresponding branches `master` and or `?.?.x` (patch).
-- It will rewrite commit history by automatically adding `Close #1234` and `(#1234)` into the commit message.
-
-NOTE: The `merge-pr` will land the PR on `master` and or `?.?.x` (patch) as described by `PR target: *` label.
-
 ### Recovering from failed `merge-pr` due to conflicts
 
-When running `merge-pr` the script will output the commands which it is about to run.
-
-```
-$ ./scripts/github/merge-pr 1234
-======================
-GitHub Merge PR Steps
-======================
-   git cherry-pick angular/pr/1234~1..angular/pr/1234
-   git filter-branch -f --msg-filter "/home/misko/angular/scripts/github/utils/github.closes 1234" HEAD~1..HEAD
-```
-
-If the `cherry-pick` command fails than resolve conflicts and use `git cherry-pick --continue` once ready. After the `cherry-pick` is done cut&paste and run the `filter-branch` command to properly rewrite the messages
-
-## Cherry-picking PRs into patch branch
-
-In addition to merging PRs into the master branch, many PRs need to be also merged into a patch branch.
-Follow these steps to get patch branch up to date.
-
-1. Check out the most recent patch branch: `git checkout 4.3.x`
-2. Get a list of PRs merged into master: `git log master --oneline -n10`
-3. For each PR number in the commit message run: `./scripts/github/merge-pr 1234`
-   - The PR will only merge if the `PR target:` matches the branch.
-
-Once all of the PRs are in patch branch, push the all branches and tags to github using `push-upstream` script.
-
-
-## Pushing merged PRs into github
-
-Use `push-upstream` script to push all of the branch and tags to github.
-
-```
-$ ./scripts/github/push-upstream
-git push git@github.com:angular/angular.git master:master 4.3.x:4.3.x
-Counting objects: 25, done.
-Delta compression using up to 6 threads.
-Compressing objects: 100% (17/17), done.
-Writing objects: 100% (25/25), 2.22 KiB | 284.00 KiB/s, done.
-Total 25 (delta 22), reused 8 (delta 7)
-remote: Resolving deltas: 100% (22/22), completed with 18 local objects.
-To github.com:angular/angular.git
-   079d884b6..d1c4a94bb  master -> master
-git push --tags -f git@github.com:angular/angular.git patch_sync:patch_sync
-Everything up-to-date
-```
+The `ng-dev pr merge` tool will automatically restore to the previous git state when a merge fails.
diff --git a/docs/COMMITTER.md b/docs/COMMITTER.md
@@ -12,7 +12,7 @@ Change approvals in our monorepo are managed via [PullApprove](https://docs.pull
 # Merging
 
 Once a change has all of the required approvals, either the last approver or the PR author (if PR author has the project collaborator status)
-should mark the PR with the `PR action: merge` label and the correct [target label](https://github.com/angular/angular/blob/master/docs/TRIAGE_AND_LABELS.md#pr-target).
+should mark the PR with the `action: merge` label and the correct [target label](https://github.com/angular/angular/blob/master/docs/TRIAGE_AND_LABELS.md#pr-target).
 This signals to the caretaker that the PR should be merged. See [merge instructions](CARETAKER.md).
 
 # Who is the Caretaker?
diff --git a/docs/TRIAGE_AND_LABELS.md b/docs/TRIAGE_AND_LABELS.md
@@ -125,28 +125,28 @@ Triaging PRs is the same as triaging issues, except that the labels `frequency:
 
 PRs also have additional label categories that should be used to signal their state.
 
-Every triaged PR must have a `PR action` label assigned to it:
+Every triaged PR must have a `action: *` label assigned to it:
 
-* `PR action: discuss`: Discussion is needed, to be led by the author.
+* `action: discuss`: Discussion is needed, to be led by the author.
   * _**Who adds it:** Typically the PR author._
   * _**Who removes it:** Whoever added it._
-* `PR action: review` (optional): One or more reviews are pending. The label is optional, since the review status can be derived from GitHub's Reviewers interface.
+* `action: review` (optional): One or more reviews are pending. The label is optional, since the review status can be derived from GitHub's Reviewers interface.
   * _**Who adds it:** Any team member. The caretaker can use it to differentiate PRs pending review from merge-ready PRs._
   * _**Who removes it:** Whoever added it or the reviewer adding the last missing review._
-* `PR action: cleanup`: More work is needed from the author.
+* `action: cleanup`: More work is needed from the author.
   * _**Who adds it:** The reviewer requesting changes to the PR._
   * _**Who removes it:** Either the author (after implementing the requested changes) or the reviewer (after confirming the requested changes have been implemented)._
-* `PR action: merge`: The PR author is ready for the changes to be merged by the caretaker as soon as the PR is green (or merge-assistance label is applied and caretaker has deemed it acceptable manually). In other words, this label indicates to "auto submit when ready".
+* `action: merge`: The PR author is ready for the changes to be merged by the caretaker as soon as the PR is green (or merge-assistance label is applied and caretaker has deemed it acceptable manually). In other words, this label indicates to "auto submit when ready".
   * _**Who adds it:** Typically the PR author._
   * _**Who removes it:** Whoever added it._
 
 
 In addition, PRs can have the following states:
 
-* `PR state: WIP`: PR is experimental or rapidly changing. Not ready for review or triage.
+* `state: WIP`: PR is experimental or rapidly changing. Not ready for review or triage.
   * _**Who adds it:** The PR author._
   * _**Who removes it:** Whoever added it._
-* `PR state: blocked`: PR is blocked on an issue or other PR. Not ready for merge.
+* `state: blocked`: PR is blocked on an issue or other PR. Not ready for merge.
   * _**Who adds it:** Any team member._
   * _**Who removes it:** Any team member._
 
@@ -162,13 +162,27 @@ This decision is then honored when the PR is being merged by the caretaker.
 
 To communicate the target we use the following labels:
 
-* `PR target: master & patch`: the PR should me merged into the master branch and cherry-picked into the most recent patch branch. All PRs with fixes, docs and refactorings should use this target.
-* `PR target: master-only`: the PR should be merged only into the `master` branch. All PRs with new features, API changes or high-risk changes should use this target.
-* `PR target: patch-only`: the PR should be merged only into the most recent patch branch (e.g. 5.0.x). This target is useful if a `master & patch` PR can't be cleanly cherry-picked into the stable branch and a new PR is needed.
-* `PR target: LTS-only`: the PR should be merged only into the active LTS branch(es). Only security and critical fixes are allowed in these branches. Always send a new PR targeting just the LTS branch and request review approval from @IgorMinar.
-* `PR target: TBD`: the target is yet to be determined.
+Targeting an active release train:
 
-If a PR is missing the `PR target: *` label, or if the label is set to "TBD" when the PR is sent to the caretaker, the caretaker should reject the PR and request the appropriate target label to be applied before the PR is merged.
+* `target: major`: Any breaking change
+* `target: minor`: Any new feature
+* `target: patch`: Bug fixes, refactorings, documentation changes, etc. that pose no or very low risk of adversely
+  affecting existing applications.
+
+Special Cases:
+* `target: rc`: A critical fix for an active release-train while it is in a feature freeze or RC phase
+* `target: lts`: A criticial fix for a specific release-train that is still within the long term support phase
+
+
+Notes:
+  - To land a change only in a patch/RC branch, without landing it in any other active release-train branch (such
+  as `master`), the patch/RC branch can be targeted in the Github UI with the appropriate
+  `target: patch`/`target: rc` label.
+  - `target: lts` PRs must target the specific LTS branch they would need to merge into in the Github UI, in
+  cases which a change is desired in multiple LTS branches, individual PRs for each LTS branch must be created
+
+
+If a PR is missing the `target:*` label, it will be marked as pending by the angular robot status checks.
 
 
 ## PR Approvals
@@ -182,7 +196,7 @@ In any case, the reviewer should actually look through the code and provide feed
 
 Note that approved state does not mean a PR is ready to be merged.
 For example, a reviewer might approve the PR but request a minor tweak that doesn't need further review, e.g., a rebase or small uncontroversial change.
-Only the `PR action: merge` label means that the PR is ready for merging.
+Only the `action: merge` label means that the PR is ready for merging.
 
 
 ## Special Labels
@@ -201,7 +215,7 @@ Only issues with `cla:yes` should be merged into master.
 
 Applying this label to a PR makes the angular.io preview available regardless of the author. [More info](../aio/aio-builds-setup/docs/overview--security-model.md)
 
-### `PR action: merge-assistance`
+### `action: merge-assistance`
 * _**Who adds it:** Any team member._
 * _**Who removes it:** Any team member._
 
@@ -211,7 +225,7 @@ The comment should be formatted like this: `merge-assistance: <explain what kind
 
 For example, the PR owner might not be a Googler and needs help to run g3sync; or one of the checks is failing due to external causes and the PR should still be merged.
 
-### `PR action: rerun CI at HEAD`
+### `action: rerun CI at HEAD`
 * _**Who adds it:** Any team member._
 * _**Who removes it:** The Angular Bot, once it triggers the CI rerun._
 
