From 14d31987b98a18f7e2a217ebbafe87e96dd77dfd Mon Sep 17 00:00:00 2001
From: Doug Parker <dgp1130@users.noreply.github.com>
Date: Fri, 17 Apr 2020 15:26:53 -0700
Subject: [PATCH] docs: add notes about various release foot-guns

This is a few different edits to make caretakers more aware of problems that can occur during a release.
* Added a comment to reinforce that pushing tags needs to happen with the push of the release commit. Otherwise CI can fail `npm install` because the relevant tags are not set.
* Changed to check out the publish branch rather than the tag because checking out a tag fails the subsequent `publish` command.
* Added `yarn` before the `publish` command because dependencies may be out of date and cause errors.
---
 docs/process/release.md | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/docs/process/release.md b/docs/process/release.md
index 7ab4def33dd0..2e638d78cc42 100644
--- a/docs/process/release.md
+++ b/docs/process/release.md
@@ -98,6 +98,9 @@ As commits are cherry-picked when PRs are merged, creating the release should be
 ```bash
 git commit -a -m 'release: vXX'
 git tag 'vXX'
+
+# Make sure to run these commands together, as missing tags can cause CI
+# failures.
 git push upstream && git push upstream --tags
 ```
 
@@ -124,29 +127,31 @@ After closing the tab, you have successfully logged in, it is time to publish.
 
 **It is a good idea to wait for CI to be green on the patch branch and tag before doing the release.**
 
-Check out the patch tag (e.g. `v6.7.8`), then run:
-```sh
-devkit-admin publish
+Check out the patch branch (e.g. `9.1.x`), then run:
+```bash
+yarn # Reload dependencies
+yarn admin publish
 ```
 
-Check out the minor tag (e.g. `v6.8.0-beta.0`), then run:
+If also publishing a prerelease, check out `master`, then run:
 ```bash
-devkit-admin publish --tag next
+yarn # Reload dependencies
+yarn admin publish --tag next
 ```
 
 ### Release Notes
 
-`devkit-admin changelog` takes `from` and `to` arguments which are any valid git
+`yarn run -s admin changelog` takes `from` and `to` arguments which are any valid git
 ref.
 
 For example, running the following command will output the release notes on
 stdout between v1.2.3 and 1.2.4:
 
 ```bash
-devkit-admin changelog --from=v1.2.3 --to=v1.2.4
+yarn run -s admin changelog --from=v1.2.3 --to=v1.2.4
 ```
 
-Copy the output (you can use `| pbcopy` on MacOS or `|xclip` on Linux) and
+Copy the output (you can use `| pbcopy` on MacOS or `| xclip` on Linux) and
 paste the release notes on [GitHub](https://github.com/angular/angular-cli/releases)
 for the tag just released.