Improve deploy doc (#7175)

DEPLOY.md

@@ -6,19 +6,11 @@ and publish the NPM module `cypress` if you are a member of the `cypress` NPM or
 > :information_source: See the [publishing](#publishing) section for how to build, test and publish a
 new official version of the binary and `cypress` NPM package.
 
-## Set next version on CIs
-
-We build the NPM package and binary on all major platforms (Linux, Mac, Windows) on different CI
-providers. In order to set the version while building we have to set the environment variable
-with the new version on each CI provider *before starting the build*.
-
-Use script command `yarn set-next-ci-version` to do this.
-
-## Building
+## Building Locally
 
 ### Building the NPM package
 
-> :warning: Note: The steps in this section are automated in CI, and you should not generally need to do them yourself.
+> :warning: Note: The steps in this section are automated in CI, and you should not need to do them yourself when publishing.
 
 Building a new NPM package is very quick.
 
@@ -31,49 +23,15 @@ The steps above:
 - Transpile the code into ES5 to be compatible with the common Node versions
 - Put the result into the [`cli/build`](./cli/build) folder.
 
-You could publish from there, but first you need to build and upload the binary with the *same version*;
-this guarantees that when users do `npm i cypress@<x.y.z>` they can download the binary
-with the same version `x.y.z` from Cypress's CDN service.
-
 ### Building the binary
 
-> :warning: Note: The steps in this section are automated in CI, and you should not generally need to do them yourself.
-
-First, you need to build, zip and upload the application binary to the Cypress server.
-
-You can use a single command to do all tasks at once:
-
-```shell
-yarn binary-deploy
-```
-
-Or you can specify each command separately:
-
-```shell
-yarn binary-build
-yarn binary-zip
-yarn binary-upload
-```
-
-You can pass options to each command to avoid answering questions, for example
-
-```shell
-yarn binary-deploy --platform darwin --version 0.20.0
-yarn binary-upload --platform darwin --version 0.20.0 --zip cypress.zip
-```
-
-If something goes wrong, see the debug messages using the `DEBUG=cypress:binary ...` environment
-variable.
+> :warning: Note: The steps in this section are automated in CI, and you should not need to do them yourself when publishing.
 
-Because we had many problems reliably zipping the built binary, for now we need to build both the Mac and Linux binary from Mac (Linux binary is built using a Docker container), then zip it **from Mac**, then upload it.
+The NPM package requires a corresponding binary of the same version. In production, it will try to retrieve the binary from the Cypress CDN if it is not cached locally.
 
-### Building Linux binary in Docker
+You can build the Cypress binary locally by running `yarn binary-build`. You can use Docker to build a Linux binary by running `yarn binary-build-linux`.
 
-If you are using a Mac you can build the linux binary if you have docker installed.
-
-```shell
-yarn binary-build-linux
-```
+`yarn binary-zip` can be used to zip the built binary together.
 
 ## Publishing
 
@@ -103,46 +61,69 @@ Once the `develop` branch for all test projects are reliably passing with the ne
 In the following instructions, "X.Y.Z" is used to denote the version of Cypress being published.
 
 0. Make sure that if there is a new [`cypress-example-kitchensink`](https://github.com/cypress-io/cypress-example-kitchensink/releases) version, the corresponding dependency in [`packages/example`](./packages/example) has been updated to that new version.
-1. Make sure that you have the correct environment variables set up before proceeding.
-    - You'll need Cypress AWS access keys in `aws_credentials_json`, which looks like this:
+1. Make sure you have the correct permissions set up before proceeding:
+    - An AWS account with permission to create AWS access keys for the Cypress CDN.
+    - Permissions for your npm account to publish the `cypress` package.
+    - Permissions to modify environment variables for `cypress` on CircleCI and AppVeyor.
+    - Permissions to update releases in ZenHub.
+2. Make sure that you have the correct environment variables set up before proceeding:
+    - Cypress AWS access key and secret in `aws_credentials_json`, which looks like this:
         ```text
         aws_credentials_json={"bucket":"cdn.cypress.io","folder":"desktop","key":"...","secret":"..."}
         ```
-    - You'll need a [GitHub token](https://github.com/settings/tokens), a [CircleCI token](https://circleci.com/account/api),
+    - A [GitHub token](https://github.com/settings/tokens), a [CircleCI token](https://circleci.com/account/api),
       and a `cypress-io` account-specific [AppVeyor token](https://ci.appveyor.com/api-keys) in `ci_json`:
         ```text
         ci_json={"githubToken":"...","circleToken":"...","appVeyorToken":"..."}
         ```
+    - You'll also need to put the GitHub token under its own variable and get a [ZenHub API token](https://app.zenhub.com/dashboard/tokens) for the `release-automations` step.
+        ```text
+        GITHUB_TOKEN="..."
+        ZENHUB_API_TOKEN="..."
+        ```
+    - The `cypress-bot` GitHub app credentials are also needed. Ask another team member who has done a deploy for those.
     - Tip: Use [as-a](https://github.com/bahmutov/as-a) to manage environment variables for different situations.
-2. Use the `move-binaries` script to move the binaries for `<commit sha>` from `beta` to the `desktop` folder
+3. Use the `move-binaries` script to move the binaries for `<commit sha>` from `beta` to the `desktop` folder
     for `<new target version>`
     ```shell
     yarn move-binaries --sha <commit sha> --version <new target version>
     ```
-3. Publish the new NPM package under the dev tag. The unique link to the package file `cypress.tgz`
-    is the one already tested above. You can publish to the NPM registry straight from the URL:
-    ```shell
-    npm publish https://cdn.../npm/X.Y.Z/<long sha>/cypress.tgz --tag dev
-    ```
-4. Double-check that the new version has been published under the `dev` tag using `npm info cypress` or [available-versions](https://github.com/bahmutov/available-versions). Example output:
+4. Publish the new NPM package under the `dev` tag, using your personal NPM account.
+    - To find the link to the package file `cypress.tgz`:
+        1. In GitHub, go to the latest commit (the one whose sha you used in the last step).
+            ![commit-link](https://user-images.githubusercontent.com/1157043/80608728-33fe6100-8a05-11ea-8b53-375303757b67.png)
+        2. Scroll down past the changes to the comments. The first comment should be a `cypress-bot` comment that includes a line beginning `npm install ...`. Grab the `https://cdn.../npm/X.Y.Z/<long sha>/cypress.tgz` link.
+            ![cdn-tgz-link](https://user-images.githubusercontent.com/1157043/80608736-3791e800-8a05-11ea-8d75-e4f80128e857.png)
+    - Publish to the NPM registry straight from the URL:
+        ```shell
+        npm publish https://cdn.../npm/X.Y.Z/<long sha>/cypress.tgz --tag dev
+        ```
+5. Double-check that the new version has been published under the `dev` tag using `npm info cypress` or [available-versions](https://github.com/bahmutov/available-versions). `latest` should still point to the previous version. Example output:
     ```shell
     dist-tags:
     dev: 3.4.0     latest: 3.3.2
     ```
-5. Test `cypress@X.Y.Z` again to make sure everything is working. You can trigger test projects from the command line (if you have the appropriate permissions)
-    ```
-    node scripts/test-other-projects.js --npm cypress@X.Y.Z --binary X.Y.Z
-    ```
-6. Test the new version of Cypress against the Cypress dashboard repo.
+6. Test `cypress@X.Y.Z` to make sure everything is working.
+    - Install the new version: `npm install -g cypress@X.Y.Z`
+    - Run a quick, manual smoke test:
+        - `cypress open`
+        - Go into a project, run a quick test, make sure things look right
+    - Optionally, do more thorough tests:
+        - Trigger test projects from the command line (if you have the appropriate permissions)
+        ```
+        node scripts/test-other-projects.js --npm cypress@X.Y.Z --binary X.Y.Z
+        ```
+        - Test the new version of Cypress against the Cypress dashboard repo.
 7. Update and publish the changelog and any release-specific documentation changes in [cypress-documentation](https://github.com/cypress-io/cypress-documentation).
 8. Make the new NPM version the "latest" version by updating the dist-tag `latest` to point to the new version:
     ```shell
     npm dist-tag add cypress@X.Y.Z
     ```
-8. Run `binary-release` to update the download server's manifest, set the next CI version, and create an empty version commit:
+9. Run `binary-release` to update the [download server's manifest](https://download.cypress.io/desktop.json) and set the next CI version:
     ```shell
-    yarn run binary-release --version X.Y.Z --commit
+    yarn run binary-release --version X.Y.Z
     ```
+    > Note: Currently, there is an [issue setting the next CI version](https://github.com/cypress-io/cypress/issues/7176) that will cause this command to fail after setting the download manifest. You will need to manually update NEXT_DEV_VERSION by logging in to CircleCI and AppVeyor.
 10. If needed, push out any updated changes to the links manifest to [`on.cypress.io`](https://github.com/cypress-io/cypress-services/tree/develop/packages/on).
 11. If needed, deploy the updated [`cypress-example-kitchensink`][cypress-example-kitchensink] to `example.cypress.io` by following [these instructions under "Deployment"](./packages/example/README.md).
 12. Update the releases in [ZenHub](https://app.zenhub.com/workspaces/test-runner-5c3ea3baeb1e75374f7b0708/reports/release):
@@ -155,11 +136,11 @@ In the following instructions, "X.Y.Z" is used to denote the version of Cypress
 16. Inside of [cypress-io/release-automations][release-automations]:
     - Publish GitHub release to [cypress-io/cypress/releases](https://github.com/cypress-io/cypress/releases) using package `set-releases`:
         ```shell
-        cd set-releases && npm run release-log -- --version X.Y.Z
+        cd packages/set-releases && npm run release-log -- --version X.Y.Z
         ```
     - Add a comment to each GH issue that has been resolved with the new published version using package `issues-in-release`:
         ```shell
-        cd issues-in-release && npm run do:comment -- --release X.Y.Z
+        cd packages/issues-in-release && npm run do:comment -- --release X.Y.Z
         ```
 17. Publish a new docker image in [`cypress-docker-images`](https://github.com/cypress-io/cypress-docker-images) under `included` for the new cypress version.
 18. Decide on the next version that we will work on. For example, if we have just released `3.7.0` we probably will work on `3.7.1` next. Set it on [CI machines](#set-next-version-on-cis).