docs(developers): add basic DEVELOPER.md and update README (#4026)

DEVELOPER.md

@@ -0,0 +1,151 @@
+# Building and Testing Protractor
+
+This document describes building, testing, and releasing Protractor, and provides an overview of
+the repository layout.
+
+## Prerequisite software
+
+The prerequisite software (Node.js, npm, git, jdk) are the same as for angular. See
+https://github.com/angular/angular/blob/master/DEVELOPER.md#prerequisite-software
+
+## Getting the sources
+
+Fork Protractor from github, then clone your fork with
+
+```
+git clone git@github.com:<github username>/protractor.git
+
+# Go to the Protractor directory:
+cd protractor
+
+# Add the main protractor repository as an upstream remote to your repository:
+git remote add upstream https://github.com/angular/protractor.git
+```
+
+## Installing and Building
+
+All Protractor dependencies come from npm. Install with
+
+```
+npm Install
+```
+
+This will also trigger our build step. The build step runs the TypeScript compiler
+and copies necessary files into the output `built` directory. To run the build step
+independently, run:
+
+```
+npm run prepublish
+```
+
+You can see the other available npm scripts in `package.json`. Note that most of these
+scripts just call our `gulp` commands, which can be seen in `gulpfile.js`.
+
+## Formatting
+
+Protractor uses clang-format to format the source code. If the source code is not properly formatted,
+the CI will fail and the PR can not be merged.
+
+You can automatically format your code by running:
+
+```
+npm run format
+```
+
+You can check that you will pass lint tests with:
+
+```
+gulp lint
+
+# or if you don't have gulp installed globally
+./node_modules/.bin/gulp lint
+```
+
+## Code layout
+
+`docs/` contains markdown documentation files.
+`lib/` contains the actual Protractor code.
+`scripts/` contains scripts used for CI setup and running tests.
+`spec/` contains e2e and unit tests and configuration files for tests.
+`testapp/` contains the code for the Angular applications that e2e tests run against.
+`website/` contains code for generating Protractor API documentation and the website at protractortest.org
+
+Most of the code is written in TypeScript, with the exception of a few js files.
+
+`lib/debugger` is for element explorer, `browser.pause`, and `browser.explore`
+`lib/driverProviders` controls how WebDriver instances are created
+`lib/frameworks` contains adapters for test frameworks such as Jasmine and Mocha
+`lib/selenium-webdriver` and `lib/webdriver-js-extender` are used ONLY for API documentation generation.
+
+## Lightning Code Walkthrough
+
+TBD.
+
+## Testing
+
+Run `npm test` to run the full test suite. This assumes that you have the testapp and a
+selenium server running. Start these as separate processes with:
+
+```
+webdriver-manager update
+webdriver-manager start
+```
+
+and
+
+```
+npm start
+```
+
+This suite is described in `scripts/test.js`. It uses some small helper functions to run commands
+as child processes and capture the results, so that we can run protractor commands which should
+result in failures and verify that we get the expected number and type of failures.
+
+The suite contains unit tests, end to end tests using the built binary, and interactive tests.
+Interactive tests are for testing `browser.pause` and element explorer.
+
+End to end tests all have configuration files which live in `spec/`. Many tests do not need
+an actual Selenium server backing them, and use the `mockSelenium` configuration, which saves
+time by not connecting to a real selenium server.
+
+## Important dependencies
+
+Protractor has very close dependencies with several other projects under the Angular umbrella:
+
+`jasminewd2` is an extension of the Jasmine test framework that adds utilities for
+working with selenium-webdriver. github.com/angular/jasminewd
+
+`blocking-proxy` is a separate binary, which handles traffic between a test script and
+webdriver. It can be turned on via a protractor configuration file, and in the future
+all logic to wait for Angular will be handled through the blocking proxy.
+github.com/angular/blocking-proxy
+
+`webdriver-manager` is a separate binary which manages installing and starting up
+the various binaries necessary for running webdriver tests. These binaries include
+specific drivers for various browsers (e.g. chromedriver) and the selenium standalone
+server.
+
+`webdriver-js-extender` extends selenium-webdriver to add Appium commands.
+github.com/angular/webdriver-js-extender
+
+## Continuous Integration
+
+PRs or changes submitted to master will automatically trigger continuous integration on two
+different services - Travis, and Circle CI. We use Travis for tests run with SauceLabs because
+we have more vm time on Travis and their integration with SauceLabs is smooth. CircleCI gives us
+greater control over the vm, which allows us to run tests against local browsers and get better
+logs.
+
+Travis runs e2e tests via SauceLabs against a variety of browsers. The essential browsers run a
+more complete test suite, `specified by spec/ciFullConf.js`. We also run a set of smoke tests
+against a larger set of browsers, which is allowed to fail - this is configured in
+`spec/ciSmokeConf.js`. This is due to flakiness in IE, Safari and older browser versions.
+We also run a small set of tests using BrowserStack to verify that our integration with their
+Selenium farm works.
+
+Circle CI runs a slightly modified version of `npm test` in a single VM. It installs
+the browsers it needs locally. Circle CI runs unit tests and a set of e2e tests against Chrome.
+
+## Releasing
+
+See `release.md` for full instructions.

README.md

@@ -1,25 +1,23 @@
 Protractor [![Build Status](https://travis-ci.org/angular/protractor.svg?branch=master)](https://travis-ci.org/angular/protractor) [![CircleCI Status](https://circleci.com/gh/angular/protractor.svg?style=shield)](https://circleci.com/gh/angular/protractor) [![Join the chat at https://gitter.im/angular/protractor](https://badges.gitter.im/angular/protractor.svg)](https://gitter.im/angular/protractor)
 ==========
 
-[Protractor](http://angular.github.io/protractor) is an end-to-end test framework for [AngularJS](http://angularjs.org/) applications. Protractor is a [Node.js](http://nodejs.org/) program built on top of [WebDriverJS](https://github.com/SeleniumHQ/selenium/wiki/WebDriverJs). Protractor runs tests against your application running in a real browser, interacting with it as a user would.
+[Protractor](http://angular.github.io/protractor) is an end-to-end test framework for [Angular](http://angular.io/) and [AngularJS](http://angularjs.org) applications. Protractor is a [Node.js](http://nodejs.org/) program built on top of [WebDriverJS](https://github.com/SeleniumHQ/selenium/wiki/WebDriverJs). Protractor runs tests against your application running in a real browser, interacting with it as a user would.
 
 Compatibility
 -------------
 
-Protractor 4 is compatible with nodejs v4 and newer. If you absolutely need to use nodejs at 0.12, use Protractor@2.
+Protractor 5 is compatible with nodejs v6 and newer.
 
-Protractor works with Angular versions greater than 1.0.6/1.1.4, and is compatible with Angular 2 applications. Note that for Angular 2 apps, the `binding` and `model` locators are not supported. We recommend using `by.css`.
+Protractor works with AngularJS versions greater than 1.0.6/1.1.4, and is compatible with Angular applications. Note that for Angular apps, the `binding` and `model` locators are not supported. We recommend using `by.css`.
 
 
 Getting Started
 ---------------
-
-The Protractor documentation for users is located in the [protractor/docs](https://github.com/angular/protractor/tree/master/docs) folder.
+See the [Protractor Website](http://www.protractortest.org) for most documentation.
 
 To get set up and running quickly:
- - The [Protractor Website](http://angular.github.io/protractor)
- - Work through the [Tutorial](http://angular.github.io/protractor/#/tutorial)
- - Take a look at the [Table of Contents](http://angular.github.io/protractor/#/toc)
+ - Work through the [Tutorial](http://www.protractortest.org/#/tutorial)
+ - See the [API](http://www.protractortest.org/#/api)
 
 Once you are familiar with the tutorial, you’re ready to move on. To modify your environment, see the Protractor Setup docs. To start writing tests, see the Protractor Tests docs.
 
@@ -36,32 +34,4 @@ Please ask usage and debugging questions on [StackOverflow](http://stackoverflow
 
 For Contributors
 ----------------
-Clone the github repository:
-
-    git clone https://github.com/angular/protractor.git
-    cd protractor
-    npm install
-    ./bin/webdriver-manager update
-    cd website
-    npm install
-    cd ..
-
-Start up a selenium server. By default, the tests expect the selenium server to be running at `http://localhost:4444/wd/hub`. A selenium server can be started with [webdriver-manager](https://github.com/angular/webdriver-manager) which is included in
-[bin/webdriver-manager](https://github.com/angular/protractor/blob/master/bin/webdriver-manager).
-
-    webdriver-manager update
-    webdriver-manager start
-
-Protractor's test suite runs against the included test application.
-
-Install the test application dependencies with:
-
-    npm run install_testapp
-
-Start that up with
-
-    npm start
-
-Then run the tests with
-
-    npm test
+See DEVELOPER.md