Merge branch 'develop' into patch-1

.gitignore

@@ -7,11 +7,13 @@ node_modules
 dist
 dist-*
 build
+.history
 .vscode
 .publish
 _test-output
 cypress.zip
 tmp/
+.nyc_output
 
 # from extension
 Cached Theme.pak
@@ -20,6 +22,9 @@ Cached Theme Material Design.pak
 # from https-proxy project
 packages/https-proxy/ca/
 
+# from desktop-gui
+packages/desktop-gui/src/jsconfig.json
+
 # from example
 packages/example/app
 packages/example/build

CONTRIBUTING.md

@@ -13,13 +13,14 @@ Thanks for taking the time to contribute! :smile:
 
 - [Report bugs](https://github.com/cypress-io/cypress/issues/new) by opening an issue.
 - [Request features](https://github.com/cypress-io/cypress/issues/new) by opening an issue.
-- Write Code for one of our core packages. [Please thoroughly read our writing code guide](#writing-code).
+- Write code for one of our core packages. [Please thoroughly read our writing code guide](#writing-code).
 
 ## Table of Contents
 
 - [CI Status](#ci-status)
 - [Code of Conduct](#code-of-conduct)
-- [Bugs & Feature Requests](#bugs-features)
+- [Opening Issues](#opening-issues)
+- [Triaging Issues](#triaging-issues)
 - [Writing Documentation](#writing-documentation)
 - [Writing Code](#writing-code)
   - [What you need to know before getting started](#what-you-need-to-know-before-getting-started)
@@ -52,7 +53,7 @@ Build status | Description
 
 All contributors are expecting to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
 
-## Bugs & Feature Requests
+## Opening Issues
 
 **The most important things to do are:**
 
@@ -84,17 +85,43 @@ For some issues, there are places you can check for more information. This may h
 
 When you file a feature request, we need you to **describe the problem you are facing first**, not just your desired solution.
 
-Often, your problem may have a lot in common with other similar problems. If we understand your use case we can compare it to other use cases and sometimes find a more powerful or more general solution which solves several problems at once. Understanding the root issue can let us merge and contextualize things. Sometimes there's already a way to solve your problem that might just not be obvious.
+Often, your problem may have a lot in common with other similar problems. If we understand your use case, we can compare it to other use cases and sometimes find a more powerful or more general solution which solves several problems at once. Understanding the root issue can let us merge and contextualize things. Sometimes there's already a way to solve your problem that might just not be obvious.
 
 Also, your proposed solution may not be compatible with the direction we want to take the product, but we may be able to come up with another solution which has approximately the same effect and does fit into the product direction.
 
 ### Reproducibility
 
 **It is nearly impossible for us to resolve many issues if we can not reproduce them. Your best chance of getting a bug looked at quickly is to provide a repository with a reproducible bug that can be cloned and run.**
 
+## Triaging Issues
+
+When an issue is opened in [cypress](https://github.com/cypress-io/cypress), we need to evaluate the issue to determine what steps should be taken next. So, when approaching new issues, there are some steps that should be taken.
+
+### 1. Is this already an open issue?
+
+Search [all issues](https://github.com/cypress-io/cypress/issues) for keywords from the issue to ensure there isn't already an issue open for this. GitHub has some [search tips](https://help.github.com/articles/searching-issues-and-pull-requests/) that may help you better find the relevant issue.
+
+### 2. Is what they are describing actually happening?
+
+The best way to determine the validity of a bug is to recreate it yourself. Follow the directions or information provided to recreate the bug that is described. Did they provide a repository that demonstrates the bug? Great - fork it and run the project and steps required. If they did not provide a repository, the best way to reproduce the issue is to have a 'sandbox' project up and running locally for Cypress. This is just a simple project with Cypress installed where you can freely edit the application under test and the tests themselves to recreate the problem.
+
+**Attempting to recreate the bug will lead to a few scenarios:**
+
+#### 1. You can not recreate the bug
+
+Leave a comment on the issue saying, "I can't reproduce this situation with the code you provided. Could you provide more information or a repository demonstrating the bug?"
+
+#### 2. You can recreate the bug
+
+Leave a comment on the issue saying "I was able to reproduce this in Cypress version x.x.x" If you know where the code is that could possibly fix this issue - link to the file or line of code from the [cypress](https://github.com/cypress-io/cypress) repo and remind the user that we are open source and that we gladly accept PRs, even if they are a work in progress.
+
+#### 3. You can tell the problem is a user error
+
+In recreating the issue, you may realize that they had a typo or used the Cypress API incorrectly, etc. Leave a comment informing the user of their error and close the issue – or ask them to close the issue if it fixes their problem.
+
 ## Writing Documentation
 
-Cypress documentation lives in separate repository with its own dependencies and build tools.
+Cypress documentation lives in a separate repository with its own dependencies and build tools.
 See [Documentation Contributing Guideline](https://github.com/cypress-io/cypress-documentation/blob/master/CONTRIBUTING.md).
 
 ## Writing code
@@ -153,14 +180,13 @@ npm run build
 npm start
 ```
 
-If there are errors building the packages, run with `DEBUG=cypress:*`
-option to see more details.
+If there are errors building the packages, prefix the commands with `DEBUG=cypress:*` to see more details.
 
-This outputs a lot of debugging lines. To focus on an individual module run with `DEBUG=cypress:launcher` for instance.
+This outputs a lot of debugging lines. To focus on an individual module, run with `DEBUG=cypress:launcher` for instance.
 
-When running `npm start` this routes through the CLI and eventually calls `npm run dev` with the proper arguments. This enables Cypress day to day development to match the logic of the built binary + CLI integration.
+When running `npm start` this routes through the CLI and eventually calls `npm run dev` with the proper arguments. This enables Cypress day-to-day development to match the logic of the built binary + CLI integration.
 
-If you want to bypass the CLI entirely you can use the `npm run dev` task and pass arguments directly.
+If you want to bypass the CLI entirely, you can use the `npm run dev` task and pass arguments directly.
 
 #### Tasks
 
@@ -280,9 +306,9 @@ npm rebuild node-sass
 
 ### Packages
 
-Generally when making contributions, you are typically making it to a small number of packages. Most of your local development work will be inside a single package at a time.
+Generally when making contributions, you are typically making them to a small number of packages. Most of your local development work will be inside a single package at a time.
 
-Each package documents how to best work with it, so simple consult the `README.md` of each package.
+Each package documents how to best work with it, so simply consult the `README.md` of each package.
 
 They will outline development and test procedures. When in doubt just look at the `scripts` of each `package.json` file. Everything we do at Cypress is contained there.
 
@@ -292,7 +318,7 @@ They will outline development and test procedures. When in doubt just look at th
 
 The repository is setup with two main (protected) branches.
 
-- `master` is the code already published in the last Cypress version
+- `master` is the code already published in the last Cypress version.
 - `develop` is the current latest "edge" code. This branch is set as the default branch, and all pull requests should be made against this branch.
 
 ### Pull Requests

DEPLOY.md

@@ -1,14 +1,14 @@
 ## Deployment
 
-Anyone can build the binary and NPM package, but you can only deploy Cypress application
-and publish NPM module `cypress` if you are a member of `cypress` NPM organization.
+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.
 
-**important** see the [publishing](#publishing) section for how to build, test and publish a
+> :warning: 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 NPM package and binary on all major platforms (Linux, Mac, Windows) on different CI
+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*.
 
@@ -18,18 +18,22 @@ Use script command `npm run set-next-ci-version` to do this.
 
 Building a new NPM package is very quick.
 
-- increment the version in the root `package.json`
+- Increment the version in the root `package.json`
 - `cd cli && npm run build`
 
-This builds the `cypress` NPM package, transpiles the code into ES5 version to be compatible
-with the common Node versions and puts the result into `cli/build` folder. You could
-publish from there, but first you need to build and upload the binary with *same version*;
+The steps above:
+
+- Build the `cypress` NPM package
+- Transpiles the code into ES5 version to be compatible with the common Node versions
+- Puts the result into the `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 same version `x.y.z` from Cypress CDN service.
+with the same version `x.y.z` from Cypress CDN service.
 
 ### Building the binary
 
-First, you need to build, zip and upload application binary to Cypress server.
+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:
 
@@ -52,16 +56,16 @@ npm run binary-deploy -- --platform darwin --version 0.20.0
 npm run binary-upload -- --platform darwin --version 0.20.0 --zip cypress.zip
 ```
 
-If something goes wrong, see debug messages using `DEBUG=cypress:binary ...` environment
+If something goes wrong, see the debug messages using the `DEBUG=cypress:binary ...` environment
 variable.
 
-Because we had many problems reliably zipping built binary, for now we need
-to build both Mac and Linux binary from Mac (Linux binary is built using
+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
 
-If you're Mac you can build the linux binary if you have docker installed.
+If you are using a Mac you can build the linux binary if you have docker installed.
 
 ```
 npm run binary-build-linux
@@ -71,37 +75,38 @@ npm run binary-build-linux
 
 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
+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.
 
-- Build the package (with new target version baked in) and the binary.
-    We build Linux and Windows binaries on CircleCI and AppVeyor.
-- upload binaries *and the new NPM package* to Cypress CDN under "beta" url
-- launch 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
+A typical installation looks like this:
 
 ```
-export CYPRESS_BINARY_VERSION=https://cdn.../binary/<new version>/hash/cypress.zip
+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 new binary and NPM package really work without breaking any of the tests.
-- Each binary and NPM package has new version inside and in the URL, for example `1.0.5`. The url
+    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
+    same commit as the binaries built by CI.
 - The upload from Mac binary will create new folder on CDN like
     `https://cdn.../desktop/1.0.5/osx64`. We need to create parallel subfolders for
-    Windows and Linux binaries. Go to AWS console and create them. In this case you would create
+    Windows and Linux binaries. Go to the AWS console and create them. In this case you would create
     folders `desktop/1.0.5/linux64` and `desktop/1.0.5/win64`.
-- Copy _the tested binaries_ from unique `binary` folder into `desktop/1.0.5` subfolders for each
+- Copy _the tested binaries_ from the unique `binary` folder into `desktop/1.0.5` subfolders for each
     platform.
-- Publish the new NPM package under dev tag. The unique link to the package file `cypress.tgz`
-    is the one already tested above. You can publish to NPM registry straight from the URL
+- 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 new version has the right tag using
+- Check that the new version has the right tag using
     [available-versions](https://github.com/bahmutov/available-versions)
 
 ```
@@ -112,15 +117,14 @@ $ vers cypress
 ```
 
 - Test `cypress@1.0.5` again to make sure everything is working. You can trigger test projects
-    from command line (if you have appropriate permissions)
+    from command line (if you have the appropriate permissions)
 
         node scripts/test-other-projects.js --npm cypress@1.0.5 --binary 1.0.5
 
-- write changelog
-- publish changelog
-- close issues (link to changelog)
-- update npm dist tag to `latest`  using `npm dist-tag add cypress@1.0.5`
-- update `manifest.json` for download server `npm run binary-release -- --version 1.0.5`
-- push out updated changes to manifest for `on.cypress.io` if needed
+- 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`.
+- 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.
 
-Take a break, you deserve it!
+Take a break, you deserve it! :sunglasses:

ISSUE_TEMPLATE.md

@@ -1,28 +1,21 @@
-<!-- **Tip** in order for us to reproduce the bug you can fork [cypress-io/cypress-test-tiny](https://github.com/cypress-io/cypress-test-tiny) repo and setup the failing test. Then just tells us the repo and branch to try! -->
-
-- Operating System:
-- Cypress Version:
-- Browser Version:
-
 ### Is this a Feature or Bug?
 
 <!-- Is this a question? Do not open an issue. Please ask your question in our chat https://gitter.im/cypress-io/cypress -->
 
 ### Current behavior:
 
+<!-- images, stack traces, etc -->
 
 ### Desired behavior:
 
+### Steps to reproduce:
 
-### How to reproduce:
-
-
-#### Test code:
+<!-- Issues without reproducible steps might get closed. *Tip* You can fork https://github.com/cypress-io/cypress-test-tiny repo, set up a failing test, then tell us the repo/branch to try. -->
 
 ```js
 
 ```
 
+### Versions
 
-### Additional Info (images, stack traces, etc)
-
+<!-- Cypress, operating system, browser -->