Merge remote-tracking branch 'origin/develop' into lint-typescript

DEPLOY.md

@@ -1,21 +1,25 @@
-## Deployment
+# Deployment
 
 Anyone can build the binary and NPM package, but you can only deploy the Cypress application
 and publish the NPM module `cypress` if you are a member of `cypress` NPM organization.
 
-> :warning: See the [publishing](#publishing) section for how to build, test and publish a
+> :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
+## 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 `npm run set-next-ci-version` to do this.
 
+## Building
+
 ### 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.
+
 Building a new NPM package is very quick.
 
 - Increment the version in the root `package.json`
@@ -33,6 +37,8 @@ with the same version `x.y.z` from Cypress 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:
@@ -63,100 +69,89 @@ 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.
 
-### Linux Docker
+### Building Linux binary in Docker
 
 If you are using a Mac you can build the linux binary if you have docker installed.
 
 ```
 npm run binary-build-linux
 ```
 
-### Publishing
+## Publishing
+
+### Before Publishing a New Version
 
 In order to publish a new `cypress` package to the NPM registry, we must build and test it across
 multiple platforms and test projects. This makes publishing *directly* into the NPM registry
-impossible. Instead we:
-
-- Build the package (with the new target version baked in) and the binary.
-- Build the Linux and Windows binaries on CircleCI and AppVeyor.
-- Upload the binaries *and the new NPM package* to the Cypress CDN under the "beta" url.
-- Launch the test CI projects, like [cypress-test-node-versions](https://github.com/cypress-io/cypress-test-node-versions) and [cypress-test-example-repos](https://github.com/cypress-io/cypress-test-example-repos) with unique urls instead of installing from the NPM registry.
-
-A typical installation looks like this:
-
-```
-export CYPRESS_INSTALL_BINARY=https://cdn.../binary/<new version>/hash/cypress.zip
-npm i https://cdn.../npm/<new version>/hash/cypress.tgz
-```
-
-- All test projects are triggered automatically by the build projects, but we need to look at CIs
-    to make sure the new binary and NPM package really work without breaking any of the tests.
-- Each binary and NPM package has the new version inside and in the URL, for example `1.0.5`. The url
-    also contains the original commit SHA from which it was built.
-- Build the Mac binary and upload (see above) to the CDN. Make sure to build it from the
-    same commit as the binaries built by CI.
-
-**next steps are about to change**
-
-*old way*
-
-- The upload from Mac binary will create new folder on CDN like `https://cdn.../desktop/1.0.5/darwin-x64`. We need to create parallel subfolders for Windows and Linux binaries. Go to the AWS console and create them. In this case you would create folders `desktop/1.0.5/linux-x64` and `desktop/1.0.5/win32-x64`.
-- Copy _the tested binaries_ from the unique `binary` folder into `desktop/1.0.5` subfolders for each platform.
-
-*new way*
-
-- run script that [finds and copies built binaries](https://github.com/cypress-io/cypress/pull/4082) for each platform into the final desktop download folder
-
-```shell
-$ npm run move-binaries -- --sha <commit sha> --version <new target version>
-```
-
-This requires AWS access information in environment variable like. A variable looks like this
-
-```text
-aws_credentials_json={"bucket": "cdn.cypress.io","folder": "desktop","key": "...","secret":"..."}
-```
-
-If you need to see verbose logs, run with `DEBUG=cypress:binary` environment variable. If you use [as-a](https://github.com/bahmutov/as-a) utility it probably looks like this for a particular commit and version
-
-```shell
-$ as-a move-binaries npm run move-binaries -- --sha 455046b928c861d4457b2ec5426a51de1fda74fd --version 3.3.0
-```
-
-**continue**
-
-- Publish the new NPM package under the dev tag. The unique link to the package file `cypress.tgz`
+impossible. Instead, we have CI set up to do the following on every commit to `develop`:
+
+1. Build the NPM package with the new target version baked in.
+2. Build the Linux/Mac binaries on CircleCI and build Windows on AppVeyor.
+3. Upload the binaries and the new NPM package to the `cdn.cypress.io` under the "beta" folder.
+4. Launch the test projects like [cypress-test-node-versions](https://github.com/cypress-io/cypress-test-node-versions) and [cypress-test-example-repos](https://github.com/cypress-io/cypress-test-example-repos) using the newly-uploaded package & binary instead of installing from the NPM registry. That installation looks like this:
+    ```
+    export CYPRESS_INSTALL_BINARY=https://cdn.../binary/<new version>/<commit hash>/cypress.zip
+    npm i https://cdn.../npm/<new version>/<commit hash>/cypress.tgz
+    ```
+
+Multiple test projects are launched for each target operating system, and the results are reported
+back to GitHub using status checks so that it is easy to see if a change has broken real-world usage
+of Cypress. You can see the progress of the test projects by opening the status checks on GitHub:
+
+![Screenshot of status checks](https://i.imgur.com/AsQwzgO.png)
+
+Once all test projects are reliably working with new changes, publishing can proceed.
+
+### Steps to Publish a 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:
+        ```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),
+      and a `cypress-io` account-specific [AppVeyor token](https://ci.appveyor.com/api-keys) in `ci_json`:
+        ```text
+        ci_json={"githubToken":"...","circleToken":"...","appVeyorToken":"..."}
+        ```
+    - 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
+    for `<new target version>`
+    ```
+    npm run 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:
-
-        $ npm publish https://cdn.../npm/1.0.5/<long sha>/cypress.tgz --tag dev
-        + cypress@1.0.5
-
-- Check that the new version has the right tag using
-    [available-versions](https://github.com/bahmutov/available-versions)
-
-        $ vers cypress
-        0.20.1                      16 days
-        0.20.2                      3 days             latest
-        1.0.5                       a few seconds ago  dev
-
-- Test `cypress@1.0.5` again to make sure everything is working. You can trigger test projects
-    from command line (if you have the appropriate permissions)
-
-        node scripts/test-other-projects.js --npm cypress@1.0.5 --binary 1.0.5
-
-- Update and publish the [changelog](https://github.com/cypress-io/cypress-documentation/blob/develop/source/guides/references/changelog.md)
-- Close issues (with a link to the changelog).
-- Update the NPM dist tag to `latest` using `npm dist-tag add cypress@1.0.5 --otp <code>`.
-- Update the `manifest.json` for download server `npm run binary-release -- --version 1.0.5`
-- Push out the updated changes to the manifest for `on.cypress.io` if needed.
-- Push out an updated kitchen sink if needed.
-- Close the release in Zenhub.
-- Bump `version` in `package.json` from `develop` branch and then merge into `master`.
-
-Use [cypress-io/release-automations][release-automations] to perform the next tasks:
-
-- publish GitHub release to [cypress-io/cypress/releases](https://github.com/cypress-io/cypress/releases) using package `set-releases` (see its README for details).
-- Add a comment to each GH issue that has been resolved with the new published version using package `issues-in-release` (see its README for details)
+    ```
+    npm publish https://cdn.../npm/3.4.0/<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):
+    ```
+    dist-tags:
+    dev: 3.4.0     latest: 3.3.2
+    ```
+5. Test `cypress@3.4.0` 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@3.4.0 --binary 3.4.0
+    ```
+6. Update and publish the changelog and any release-specific documentation changes in [cypress-documentation](https://github.com/cypress-io/cypress-documentation).
+7. Make the new NPM version the "latest" version by updating the dist-tag `latest` to point to the new version:
+    ```
+    npm dist-tag add cypress@3.4.0
+    ```
+8. Run `binary-release` to update the download server's manifest, set the next CI version, and create an empty version commit:
+    ```
+    npm run binary-release -- --version 3.4.0 --commit`
+    ```
+9. Tag the current commit with `v3.4.0` and push that tag up.
+10. If needed, push out the updated changes to the docs manifest to `on.cypress.io`.
+11. If needed, push out an updated kitchen sink.
+12. Close the release in [ZenHub](https://app.zenhub.com/workspaces/test-runner-5c3ea3baeb1e75374f7b0708/reports/release).
+13. Bump `version` in `package.json` from `develop` branch and then merge into `master`.
+14. Using [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` (see its README for details).
+    - Add a comment to each GH issue that has been resolved with the new published version using package `issues-in-release` (see its README for details)
 
 Take a break, you deserve it! :sunglasses:
 

PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,10 @@
 <!--
 Thanks for contributing!
 
-Please explain what changes were made and also
-reference any issues that were fixed with #[ISSUE]
+- Add tests! This is what we do afterall. 😉
+- If you haven't already, complete the CLA.
+
+Read more about contributing: https://github.com/cypress-io/cypress/blob/develop/CONTRIBUTING.md
 -->
+
+- close <!--Add issue number here -->

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cypress",
-  "version": "3.3.2",
+  "version": "3.4.0",
   "private": true,
   "scripts": {
     "all": "node ./scripts/run.js",