docs(CHANGELOG.md): add changes for 1.6.8

The original fix for #16312 included changing how `$location.url(value)`
decoded the special characters passed to it as a setter.
This broke a number of use cases (mostly involving the ui-router).

Further analysis appears to show that we can solve #16312, to prevent
urls being rewritten with decoded values, without modifying the
behaviour of `$location.url`.

This commit reverts changes to `$location.url(value)` so that encoded
chars will once again be decoded and passed to `$location.path(value)`.
In particular it will convert encoded forward slashes, which changes how
the path is updated, since e.g. `a/b/%2Fc%2Fd` will become `a/b/c/d`.
While this is arguably not "correct", it appears that there are too many
use cases relying upon this behaviour.

.github/ISSUE_TEMPLATE.md

@@ -1,27 +1,37 @@
-***Note*: for support questions, please use one of these channels: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#question. This repository's issues are reserved for feature requests and bug reports.**
+<!--
+IF YOU DON'T FILL OUT THE FOLLOWING INFORMATION WE MIGHT CLOSE YOUR ISSUE WITHOUT INVESTIGATION
+-->
 
-**Do you want to request a *feature* or report a *bug*?**
+<!--
+- For *SUPPORT QUESTIONS*, use one of the
+[support channels](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#question).
+- Before submitting, please **SEARCH GITHUB** for a similar issue or PR. -->
 
+**I'm submitting a ...**
+<!-- (check one with "x") -->
+- [ ] bug report
+- [ ] feature request
+- [ ] other <!--(Please do not submit support requests here - see above)-->
 
+**Current behavior:**
+<!-- Describe how the bug manifests / how the current features are insufficient. -->
 
-**What is the current behavior?**
+**Expected / new behavior:**
+<!-- Describe what the behavior would be without the bug / how the feature would improve AngularJS -->
 
+**Minimal reproduction of the problem with instructions:**
+<!--
+If the current behavior is a bug or you can illustrate your feature request better with an example,
+please provide the *STEPS TO REPRODUCE* and if possible a *MINIMAL DEMO* of the problem via
+https://plnkr.co or similar (you can use this template as a starting point: http://plnkr.co/edit/tpl:yBpEi4).
+-->
 
+**AngularJS version:** 1.x.y
+<!-- Check whether this is still an issue in the most recent stable or in the snapshot AngularJS
+version (https://code.angularjs.org/snapshot/) -->
 
-**If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem via https://plnkr.co or similar (template: http://plnkr.co/edit/tpl:yBpEi4).**
+**Browser:** [all | Chrome XX | Firefox XX | Edge XX | IE XX | Safari XX | Mobile Chrome XX | Android X.X Web Browser | iOS XX Safari | iOS XX UIWebView | iOS XX WKWebView ]
+<!-- All browsers where this could be reproduced (and Operating System if relevant) -->
 
-
-
-**What is the expected behavior?**
-
-
-
-**What is the motivation / use case for changing the behavior?**
-
-
-
-**Which versions of Angular, and which browser / OS are affected by this issue? Did this work in previous versions of Angular? Please also test with the latest stable and snapshot (https://code.angularjs.org/snapshot/) versions.**
-
-
-
-**Other information (e.g. stacktraces, related issues, suggestions how to fix)**
+**Anything else:**
+<!-- e.g. stacktraces, related issues, suggestions how to fix -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,3 +1,4 @@
+<!-- General PR submission guidelines https://github.com/angular/angular.js/CONTRIBUTING.md#submit-pr -->
 **What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)**
 
 
@@ -15,9 +16,9 @@
 
 
 **Please check if the PR fulfills these requirements**
-- [ ] The commit message follows our guidelines: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit-message-format
-- [ ] Tests for the changes have been added (for bug fixes / features)
-- [ ] Docs have been added / updated (for bug fixes / features)
+- [ ] The commit message follows our [guidelines](../DEVELOPERS.md#commits)
+- [ ] Fix/Feature: [Docs](../DEVELOPERS.md#documentation) have been added/updated
+- [ ] Fix/Feature: Tests have been added; existing tests pass
 
 **Other information**:
 

.mailmap

@@ -0,0 +1,29 @@
+Andres Ornelas <aornelas@google.com>
+Caitlin Potter <caitpotter88@gmail.com>
+Caitlin Potter <caitpotter88@gmail.com> <snowball@defpixel.com>
+Di Peng <pengdi@google.com>
+Di Peng <pengdi@google.com> <pengdi@go.wustl.edu>
+Georgios Kalpakas <kalpakas.g@gmail.com>
+Georgios Kalpakas <kalpakas.g@gmail.com> <g.kalpakas@hotmail.com>
+Julie Ralph <ju.ralph@gmail.com>
+Lucas Galfaso <lgalfaso@gmail.com>
+Martin Staffa <mjstaffa@gmail.com>
+Martin Staffa <mjstaffa@gmail.com> <mjstaffa@googlemail.com>
+Matias Niemelä <matias@yearofmoo.com>
+Michał Gołębiowski-Owczarek <m.goleb@gmail.com>
+Misko Hevery <misko@hevery.com>
+Misko Hevery <misko@hevery.com> <misko@google.com>
+Igor Minar <igor@angularjs.org>
+Igor Minar <igor@angularjs.org> <iiminar@gmail.com>
+Igor Minar <igor@angularjs.org> <iminar@google.com>
+Igor Minar <igor@angularjs.org> <iminar@dhcp-172-19-37-154.mtv.corp.google.com>
+Pawel Kozlowski <pkozlowski.opensource@gmail.com>
+Peter Bacon Darwin <pete@bacondarwin.com>
+Rodric Haddad <rody@rodyhaddad.com>
+Shahar Talmi <shahar.talmi@gmail.com>
+Shahar Talmi <shahar.talmi@gmail.com> <shahart@wix.com>
+Shyam Seshadri <shyamseshadri@google.com>
+Shyam Seshadri <shyamseshadri@google.com> <shyamseshadri@gmail.com>
+Vojta Jina <vojta.jina@gmail.com>
+Vojta Jina <vojta.jina@gmail.com> <vojta@gemin-i.org>
+Vojta Jina <vojta.jina@gmail.com> <vojta@google.com>

.nvmrc

@@ -1 +1 @@
-6
+8

.travis.yml

@@ -1,7 +1,7 @@
 language: node_js
 sudo: false
 node_js:
-  - '6'
+  - '8'
 
 cache:
   yarn: true
@@ -15,29 +15,20 @@ branches:
 env:
   matrix:
     - JOB=ci-checks
-    - JOB=unit BROWSER_PROVIDER=saucelabs
-    - JOB=docs-e2e BROWSER_PROVIDER=saucelabs
+    - JOB=unit-core BROWSER_PROVIDER=saucelabs
+    - JOB=unit-jquery BROWSER_PROVIDER=saucelabs
+    - JOB=docs-app BROWSER_PROVIDER=saucelabs
     - JOB=e2e TEST_TARGET=jqlite BROWSER_PROVIDER=saucelabs
     - JOB=e2e TEST_TARGET=jquery BROWSER_PROVIDER=saucelabs
   global:
-    # node 4 likes the G++ v4.8 compiler
-    # see https://docs.travis-ci.com/user/languages/javascript-with-nodejs#Node.js-v4-(or-io.js-v3)-compiler-requirements
-    - CXX=g++-4.8
     - SAUCE_USERNAME=angular-ci
     - SAUCE_ACCESS_KEY=9b988f434ff8-fbca-8aa4-4ae3-35442987
     - LOGS_DIR=/tmp/angular-build/logs
     - BROWSER_PROVIDER_READY_FILE=/tmp/browsersprovider-tunnel-ready
     - secure: oTBjhnOKhs0qDSKTf7fE4f6DYiNDPycvB7qfSF5QRIbJK/LK/J4UtFwetXuXj79HhUZG9qnoT+5e7lPaiaMlpsIKn9ann7ffqFWN1E8TMtpJF+AGigx3djYElwfgf5nEnFUFhwjFzvbfpZNnxVGgX5YbIZpe/WUbHkP4ffU0Wks=
 
-addons:
-  apt:
-    sources:
-      - ubuntu-toolchain-r-test
-    packages:
-      - g++-4.8
-
 before_install:
-  - curl -o- -L https://yarnpkg.com/install.sh | bash -s -- --version 0.27.5
+  - curl -o- -L https://yarnpkg.com/install.sh | bash -s -- --version 1.3.2
   - export PATH="$HOME/.yarn/bin:$PATH"
 
 before_script:
@@ -63,41 +54,52 @@ notifications:
 jobs:
   include:
     - stage: deploy
+      # Don't deploy from PRs. Only deploy from our default branches, or if commit is tagged.
+      # This is a Travis-specific boolean language: https://docs.travis-ci.com/user/conditional-builds-stages-jobs#Specifying-conditions
+      # The deployment logic for pushed branches is further defined in scripts\travis\build.sh
+      if: type != pull_request and (branch =~ ^(v1\.\d+\.x|master)$ or tag IS present)
       env:
         - JOB=deploy
       before_script: skip
       script:
-        - "./scripts/travis/build.sh"
+        # Export the variables into the current process
+        - . ./scripts/travis/build.sh
+        - "echo DEPLOY_DOCS: $DEPLOY_DOCS, DEPLOY_CODE: $DEPLOY_CODE"
+      after_script: skip
       # Work around the 10min Travis timeout so the code.angularjs firebase+gcs code deploy can complete
+      # Only run the keep_alive once (before_deploy is run for each provider)
       before_deploy: |
-        function keep_alive() {
-          while true; do
-            echo -en "\a"
-            sleep 5
-          done
-        }
-        keep_alive &
+        if ! [ "$BEFORE_DEPLOY_RUN" ]; then
+          export BEFORE_DEPLOY_RUN=1;
+
+          function keep_alive() {
+            while true; do
+              echo -en "\a"
+              sleep 10
+            done
+          }
+          keep_alive &
+        fi
       deploy:
         - provider: firebase
+          # the upload folder for firebase is configured in /firebase.json
           skip_cleanup: true
           token:
             secure: $FIREBASE_TOKEN
           on:
             repo: angular/angular.js
             all_branches: true
-            # deploy a new docs version when the commit is tagged on the "latest" npm version
-            condition: $TRAVIS_TAG != '' && $( jq ".distTag" "package.json" | tr -d "\"[:space:]" ) = latest
+            condition: "$DEPLOY_DOCS == true"
         - provider: gcs
           skip_cleanup: true
           access_key_id: GOOGLDB7W2J3LFHICF3R
           secret_access_key:
             secure: tHIFdSq55qkyZf9zT/3+VkhUrTvOTMuswxXU3KyWaBrSieZqG0UnUDyNm+n3lSfX95zEl/+rJAWbfvhVSxZi13ndOtvRF+MdI1cvow2JynP0aDSiPffEvVrZOmihD6mt2SlMfhskr5FTduQ69kZG6DfLcve1PPDaIwnbOv3phb8=
           bucket: code-angularjs-org-338b8.appspot.com
-          local-dir: upload
+          local-dir: uploadCode
           detect_encoding: true # detects gzip compression
           on:
             repo: angular/angular.js
             all_branches: true
-            # upload the build when the commit is tagged or the branch is "master"
-            condition: $TRAVIS_TAG != '' || ($TRAVIS_PULL_REQUEST = false && $TRAVIS_BRANCH = master)
+            condition: "$DEPLOY_CODE == true"
 

CHANGELOG.md

@@ -1,3 +1,80 @@
+<a name="1.6.8"></a>
+# 1.6.8 beneficial-tincture (2017-12-18)
+
+
+## Bug Fixes
+- **$location:**
+  - always decode special chars in `$location.url(value)`
+  ([2bdf71](https://github.com/angular/angular.js/commit/2bdf7126878c87474bb7588ce093d0a3c57b0026))
+  - decode non-component special chars in Hashbang URLS
+  ([57b626](https://github.com/angular/angular.js/commit/57b626a673b7530399d3377dfe770165bec35f8a))
+- **ngModelController:** allow $overrideModelOptions to set updateOn
+  ([55516d](https://github.com/angular/angular.js/commit/55516da2dfc7c5798dce24e9fa930c5ac90c900c),
+  [#16351](https://github.com/angular/angular.js/issues/16351),
+  [#16364](https://github.com/angular/angular.js/issues/16364))
+
+
+## New Features
+- **$parse:** add a hidden interface to retrieve an expression's AST
+  ([f33d95](https://github.com/angular/angular.js/commit/f33d95cfcff6fd0270f92a142df8794cca2013ad),
+  [#16253](https://github.com/angular/angular.js/issues/16253),
+  [#16260](https://github.com/angular/angular.js/issues/16260))
+
+<a name="1.6.7"></a>
+# 1.6.7 imperial-backstroke (2017-11-24)
+
+
+## Bug Fixes
+- **$compile:** sanitize special chars in directive name
+  ([c4003f](https://github.com/angular/angular.js/commit/c4003fd03489f876b646f06838f4edb576bacf6f),
+  [#16314](https://github.com/angular/angular.js/issues/16314),
+  [#16278](https://github.com/angular/angular.js/issues/16278))
+- **$location:** do not decode forward slashes in the path in HTML5 mode
+  ([e06ebf](https://github.com/angular/angular.js/commit/e06ebfdbb558544602fe9da4d7d98045a965f468),
+  [#16312](https://github.com/angular/angular.js/issues/16312))
+- **sanitizeUri:** sanitize URIs that contain IDEOGRAPHIC SPACE chars
+  ([ddeb1d](https://github.com/angular/angular.js/commit/ddeb1df15a23de93eb95dbe202e83e93673e1c4e),
+  [#16288](https://github.com/angular/angular.js/issues/16288))
+- **$rootScope:** fix potential memory leak when removing scope listeners
+  ([358a69](https://github.com/angular/angular.js/commit/358a69fa8b89b251ee44e523458d6c7f40b92b2d),
+  [#16135](https://github.com/angular/angular.js/issues/16135),
+  [#16161](https://github.com/angular/angular.js/issues/16161))
+- **http:** do not allow encoded callback params in jsonp requests
+  ([569e90](https://github.com/angular/angular.js/commit/569e906a5818271416ad0b749be2f58dc34938bd))
+- **ngMock:** pass unexpected request failures in `$httpBackend` to the error handler
+  ([1555a4](https://github.com/angular/angular.js/commit/1555a4911ad5360c145c0ddc8ec6c4bf9a381c13),
+  [#16150](https://github.com/angular/angular.js/issues/16150),
+  [#15855](https://github.com/angular/angular.js/issues/15855))
+- **ngAnimate:** don't close transitions when child transitions close
+  ([1391e9](https://github.com/angular/angular.js/commit/1391e99c7f73795180b792af21ad4402f96e225d),
+  [#16210](https://github.com/angular/angular.js/issues/16210))
+- **ngMock.browserTrigger:** add 'bubbles' to Transition/Animation Event
+  ([7a5f06](https://github.com/angular/angular.js/commit/7a5f06d55d123a39bb7b030667fb1ab672939598))
+
+
+## New Features
+- **$sanitize, $compileProvider, linky:** add support for the "sftp" protocol in links
+  ([a675ea](https://github.com/angular/angular.js/commit/a675ea034366fbb0fcf0d73fed65216aa99bce11),
+  [#16102](https://github.com/angular/angular.js/issues/16102))
+- **ngModel.NgModelController:** expose $processModelValue to run model -> view pipeline
+  ([145194](https://github.com/angular/angular.js/commit/14519488ce9218aa891d34e89fc3271fd4ed0f04),
+  [#3407](https://github.com/angular/angular.js/issues/3407),
+  [#10764](https://github.com/angular/angular.js/issues/10764),
+  [#16237](https://github.com/angular/angular.js/issues/16237))
+- **$injector:** ability to load new modules after bootstrapping
+  ([6e78fe](https://github.com/angular/angular.js/commit/6e78fee73258bb0ae36414f9db2e8734273e481b))
+
+
+## Performance Improvements
+- **jqLite:**
+  - avoid setting class attribute when not changed
+  ([9c95f6](https://github.com/angular/angular.js/commit/9c95f6d5e00ee7e054aabb3e363f5bfb3b7b4103))
+  - avoid repeated add/removeAttribute in jqLiteRemoveClass
+  ([cab9eb](https://github.com/angular/angular.js/commit/cab9ebfd5a02e897f802bf6321b8471e4843c5d3),
+  [#16078](https://github.com/angular/angular.js/issues/16078),
+  [#16131](https://github.com/angular/angular.js/issues/16131))
+
+
 <a name="1.6.6"></a>
 # 1.6.6 interdimensional-cable (2017-08-18)
 

CONTRIBUTING.md

@@ -3,85 +3,101 @@
 We'd love for you to contribute to our source code and to make AngularJS even better than it is
 today! Here are the guidelines we'd like you to follow:
 
- - [Code of Conduct](#coc)
- - [Question or Problem?](#question)
- - [Issues and Bugs](#issue)
- - [Feature Requests](#feature)
- - [Submission Guidelines](#submit)
- - [Coding Rules](#rules)
- - [Commit Message Guidelines](#commit)
- - [Signing the CLA](#cla)
- - [Further Info](#info)
+* [Code of Conduct](#coc)
+* [Questions and Problems](#question)
+* [Issues and Bugs](#issue)
+* [Feature Requests](#feature)
+* [Improving Documentation](#docs)
+* [Issue Submission Guidelines](#submit)
+* [Pull Request Submission Guidelines](#submit-pr)
+* [Signing the CLA](#cla)
 
 ## <a name="coc"></a> Code of Conduct
 
-Help us keep Angular open and inclusive. Please read and follow our [Code of Conduct][coc].
+Help us keep AngularJS open and inclusive. Please read and follow our [Code of Conduct][coc].
 
-## <a name="question"></a> Got a Question or Problem?
+## <a name="requests"></a> Questions, Bugs, Features
 
-If you have questions about how to use AngularJS, please direct these to the [Google Group][groups]
-discussion list or [StackOverflow][stackoverflow]. We are also available on [IRC][irc] and
-[Gitter][gitter].
+### <a name="question"></a> Got a Question or Problem?
 
-## <a name="issue"></a> Found an Issue?
+Do not open issues for general support questions as we want to keep GitHub issues for bug reports
+and feature requests. You've got much better chances of getting your question answered on dedicated
+support platforms, the best being [Stack Overflow][stackoverflow].
 
-If you find a bug in the source code or a mistake in the documentation, you can help us by
-submitting an issue to our [GitHub Repository][github]. Even better you can submit a Pull Request
-with a fix.
+Stack Overflow is a much better place to ask questions since:
 
-**Localization Issues:** Angular.js uses the [Google Closure I18N library] to generate
-its own I18N files (the ngLocale module). This means that any changes to these files would be lost
-the next time that we import the library.
+- there are thousands of people willing to help on Stack Overflow
+- questions and answers stay available for public viewing so your question / answer might help
+  someone else
+- Stack Overflow's voting system assures that the best answers are prominently visible.
+
+To save your and our time, we will systematically close all issues that are requests for general
+support and redirect people to the section you are reading right now.
+
+Other channels for support are:
+- the [Google Group][groups] discussion list
+- the [AngularJS IRC][irc]
+- the [AngularJS Gitter][gitter]
+
+### <a name="issue"></a> Found an Issue or Bug?
+
+If you find a bug in the source code, you can help us by submitting an issue to our
+[GitHub Repository][github]. Even better, you can submit a Pull Request with a fix.
+
+**Please see the [Submission Guidelines](#submit) below.**
+
+**Special Note for Localization Issues:** AngularJS uses the [Google Closure I18N library] to
+generate its own I18N files (the ngLocale module). This means that any changes to these files
+would be lost the next time that we import the library.
 Since the Closure library i18n data is itself auto-generated from the data of the
 [Common Locale Data Repository (CLDR)] project, errors in the data should
 be reported there. See also the [Closure guide to i18n changes].
 
-**Please see the [Submission Guidelines](#submit) below.**
+### <a name="feature"></a> Missing a Feature?
 
-## <a name="feature"></a> Want a Feature?
+You can request a new feature by submitting an issue to our [GitHub Repository][github-issues].
 
-You can request a new feature by submitting an issue to our [GitHub Repository][github].  If you
-would like to implement a new feature then consider what kind of change it is:
+If you would like to implement a new feature then consider what kind of change it is:
 
-* **Major Changes** that you wish to contribute to the project should be discussed first on our
-  [dev mailing list][angular-dev] or [IRC][irc] so that we can better coordinate our efforts,
-  prevent duplication of work, and help you to craft the change so that it is successfully accepted
-  into the project.
-* **Small Changes** can be crafted and submitted to the [GitHub Repository][github] as a Pull
-  Request.
+* **Major Changes** that you wish to contribute to the project should be discussed first in an
+  [GitHub issue][github-issues] that clearly outlines the changes and benefits of the feature.
+* **Small Changes** can directly be crafted and submitted to the [GitHub Repository][github]
+  as a Pull Request. See the section about [Pull Request Submission Guidelines](#submit-pr), and
+  for detailed information the [core development documentation][developers].
 
+### <a name="docs"></a> Want a Doc Fix?
 
-## <a name="docs"></a> Want a Doc Fix?
+Should you have a suggestion for the documentation, you can open an issue and outline the problem
+or improvement you have - however, creating the doc fix yourself is much better!
 
 If you want to help improve the docs, it's a good idea to let others know what you're working on to
 minimize duplication of effort. Create a new issue (or comment on a related existing one) to let
 others know what you're working on.
 
+If you're making a small change (typo, phrasing) don't worry about filing an issue first. Use the
+friendly blue "Improve this doc" button at the top right of the doc page to fork the repository
+in-place and make a quick change on the fly. The commit message is preformatted to the right type
+and scope, so you only have to add the description.
+
 For large fixes, please build and test the documentation before submitting the PR to be sure you
 haven't accidentally introduced any layout or formatting issues. You should also make sure that your
-commit message starts with "docs" and follows the **[Commit Message Guidelines](#commit)** outlined
-below.
+commit message follows the **[Commit Message Guidelines][developers.commits]**.
 
-If you're just making a small change, don't worry about filing an issue first. Use the friendly blue
-"Improve this doc" button at the top right of the doc page to fork the repository in-place and make
-a quick change on the fly. When naming the commit, it is advised to follow the commit message
-guidelines below, by starting the commit message with **docs** and referencing the filename. Since
-this is not obvious and some changes are made on the fly, this is not strictly necessary and we will
-understand if this isn't done the first few times.
-
-## <a name="submit"></a> Submission Guidelines
-
-### Submitting an Issue
+## <a name="submit"></a> Issue Submission Guidelines
 Before you submit your issue search the archive, maybe your question was already answered.
 
 If your issue appears to be a bug, and hasn't been reported, open a new issue. Help us to maximize
 the effort we can spend fixing issues and adding new features, by not reporting duplicate issues.
-Providing the following information will increase the chances of your issue being dealt with
-quickly:
+
+The "[new issue][github-new-issue]" form contains a number of prompts that you should fill out to
+make it easier to understand and categorize the issue.
+
+In general, providing the following information will increase the chances of your issue being dealt
+with quickly:
 
 * **Overview of the Issue** - if an error is being thrown a non-minified stack trace helps
 * **Motivation for or Use Case** - explain why this is a bug for you
-* **Angular Version(s)** - is it a regression?
+* **AngularJS Version(s)** - is it a regression?
 * **Browsers and Operating System** - is this a problem with all browsers or only specific ones?
 * **Reproduce the Error** - provide a live example (using [Plunker][plunker] or
   [JSFiddle][jsfiddle]) or an unambiguous set of steps.
@@ -89,41 +105,43 @@ quickly:
 * **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be
   causing the problem (line of code or commit)
 
-Here is a great example of a well defined issue: https://github.com/angular/angular.js/issues/5069
+Here is a great example of a well defined issue: https://github.com/angular/angular.js/issues/5069.
 
 **If you get help, help others. Good karma rulez!**
 
-### Submitting a Pull Request
+## <a name="submit-pr"></a> Pull Request Submission Guidelines
 Before you submit your pull request consider the following guidelines:
 
 * Search [GitHub](https://github.com/angular/angular.js/pulls) for an open or closed Pull Request
   that relates to your submission. You don't want to duplicate effort.
-* Please sign our [Contributor License Agreement (CLA)](#cla) before sending pull
-  requests. We cannot accept code without this.
+* Create the [development environment][developers.setup]
 * Make your changes in a new git branch:
 
     ```shell
     git checkout -b my-fix-branch master
     ```
 
-* Create your patch, **including appropriate test cases**.
-* Follow our [Coding Rules](#rules).
-* Run the full Angular test suite, as described in the [developer documentation][dev-doc],
-  and ensure that all tests pass.
+* Create your patch commit, **including appropriate test cases**.
+* Follow our [Coding Rules][developers.rules].
+* If the changes affect public APIs, change or add relevant [documentation][developers.documentation].
+* Run the AngularJS [unit][developers.tests-unit] and [E2E test][developers.tests-e2e] suites, and ensure that all tests
+  pass. It is generally sufficient to run the tests only on Chrome, as our Travis integration will
+  run the tests on all supported browsers.
+* Run `yarn grunt eslint` to check that you have followed the automatically enforced coding rules
 * Commit your changes using a descriptive commit message that follows our
-  [commit message conventions](#commit) and passes our commit message presubmit hook
-  (`validate-commit-msg.js`). Adherence to the [commit message conventions](#commit) is required,
-  because release notes are automatically generated from these messages.
+  [commit message conventions][developers.commits]. Adherence to the
+  [commit message conventions][developers.commits] is required, because release notes are
+  automatically generated from these messages.
 
     ```shell
     git commit -a
     ```
   Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files.
 
-* Build your changes locally to ensure all the tests pass:
+* Before creating the Pull Request, package and run all tests a last time:
 
     ```shell
-    grunt test
+    yarn grunt test
     ```
 
 * Push your branch to GitHub:
@@ -132,24 +150,30 @@ Before you submit your pull request consider the following guidelines:
     git push origin my-fix-branch
     ```
 
-In GitHub, send a pull request to `angular:master`.
-If we suggest changes, then:
+* In GitHub, send a pull request to `angular.js:master`. This will trigger the check of the
+[Contributor License Agreement](#cla) and the Travis integration.
 
-* Make the required updates.
-* Re-run the Angular test suite to ensure tests are still passing.
-* Commit your changes to your branch (e.g. `my-fix-branch`).
-* Push the changes to your GitHub repository (this will update your Pull Request).
+* If you find that the Travis integration has failed, look into the logs on Travis to find out
+if your changes caused test failures, the commit message was malformed etc. If you find that the
+tests failed or times out for unrelated reasons, you can ping a team member so that the build can be
+restarted.
 
-If the PR gets too outdated we may ask you to rebase and force push to update the PR:
+* If we suggest changes, then:
 
-```shell
-git rebase master -i
-git push origin my-fix-branch -f
-```
+  * Make the required updates.
+  * Re-run the AngularJS test suite to ensure tests are still passing.
+  * Commit your changes to your branch (e.g. `my-fix-branch`).
+  * Push the changes to your GitHub repository (this will update your Pull Request).
 
-_WARNING: Squashing or reverting commits and force-pushing thereafter may remove GitHub comments
-on code that were previously made by you or others in your commits. Avoid any form of rebasing
-unless necessary._
+    You can also amend the initial commits and force push them to the branch.
+
+    ```shell
+    git rebase master -i
+    git push origin my-fix-branch -f
+    ```
+
+    This is generally easier to follow, but seperate commits are useful if the Pull Request contains
+    iterations that might be interesting to see side-by-side.
 
 That's it! Thank you for your contribution!
 
@@ -182,135 +206,41 @@ from the main (upstream) repository:
     git pull --ff upstream master
     ```
 
-## <a name="rules"></a> Coding Rules
+## <a name="cla"></a> Signing the Contributor License Agreement (CLA)
 
-To ensure consistency throughout the source code, keep these rules in mind as you are working:
-
-* All features or bug fixes **must be tested** by one or more [specs][unit-testing].
-* All public API methods **must be documented** with ngdoc, an extended version of jsdoc (we added
-  support for markdown and templating via @ngdoc tag). To see how we document our APIs, please check
-  out the existing ngdocs and see [this wiki page][ngDocs].
-* With the exceptions listed below, we follow the rules contained in
-  [Google's JavaScript Style Guide][js-style-guide]:
-    * **Do not use namespaces**: Instead,  wrap the entire angular code base in an anonymous closure and
-      export our API explicitly rather than implicitly.
-    * Wrap all code at **100 characters**.
-    * Instead of complex inheritance hierarchies, we **prefer simple objects**. We use prototypal
-      inheritance only when absolutely necessary.
-    * We **love functions and closures** and, whenever possible, prefer them over objects.
-    * To write concise code that can be better minified, we **use aliases internally** that map to the
-      external API. See our existing code to see what we mean.
-    * We **don't go crazy with type annotations** for private internal APIs unless it's an internal API
-      that is used throughout AngularJS. The best guidance is to do what makes the most sense.
-
-## <a name="commit"></a> Git Commit Guidelines
-
-We have very precise rules over how our git commit messages can be formatted.  This leads to **more
-readable messages** that are easy to follow when looking through the **project history**.  But also,
-we use the git commit messages to **generate the AngularJS change log**.
-
-The commit message formatting can be added using a typical git workflow or through the use of a CLI
-wizard ([Commitizen](https://github.com/commitizen/cz-cli)). To use the wizard, run `yarn run commit`
-in your terminal after staging your changes in git.
-
-### Commit Message Format
-Each commit message consists of a **header**, a **body** and a **footer**.  The header has a special
-format that includes a **type**, a **scope** and a **subject**:
-
-```
-<type>(<scope>): <subject>
-<BLANK LINE>
-<body>
-<BLANK LINE>
-<footer>
-```
-
-The **header** is mandatory and the **scope** of the header is optional.
-
-Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
-to read on GitHub as well as in various git tools.
-
-### Revert
-If the commit reverts a previous commit, it should begin with `revert: `, followed by the header of the reverted commit.
-In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.
-
-### Type
-Must be one of the following:
-
-* **feat**: A new feature
-* **fix**: A bug fix
-* **docs**: Documentation only changes
-* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
-  semi-colons, etc)
-* **refactor**: A code change that neither fixes a bug nor adds a feature
-* **perf**: A code change that improves performance
-* **test**: Adding missing or correcting existing tests
-* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
-  generation
-
-### Scope
-The scope could be anything specifying place of the commit change. For example `$location`,
-`$browser`, `$compile`, `$rootScope`, `ngHref`, `ngClick`, `ngView`, etc...
-
-You can use `*` when the change affects more than a single scope.
-
-### Subject
-The subject contains succinct description of the change:
-
-* use the imperative, present tense: "change" not "changed" nor "changes"
-* don't capitalize first letter
-* no dot (.) at the end
-
-### Body
-Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes".
-The body should include the motivation for the change and contrast this with previous behavior.
-
-### Footer
-The footer should contain any information about **Breaking Changes** and is also the place to
-[reference GitHub issues that this commit closes][closing-issues].
-
-**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines.
-The rest of the commit message is then used for this.
-
-A detailed explanation can be found in this [document][commit-message-format].
-
-## <a name="cla"></a> Signing the CLA
-
-Please sign our Contributor License Agreement (CLA) before sending pull requests. For any code
-changes to be accepted, the CLA must be signed. It's a quick process, we promise!
+Upon submmitting a Pull Request, a friendly bot will ask you to sign our CLA if you haven't done
+so before. Unfortunately, this is necessary for documentation changes, too.
+It's a quick process, we promise!
 
 * For individuals we have a [simple click-through form][individual-cla].
 * For corporations we'll need you to
   [print, sign and one of scan+email, fax or mail the form][corporate-cla].
 
-## <a name="info"></a> Further Information
-You can find out more detailed information about contributing in the
-[AngularJS documentation][contributing].
 
 
-
-[Google Closure I18N library]: https://github.com/google/closure-library/tree/master/closure/goog/i18n
-[angular-dev]: https://groups.google.com/forum/?fromgroups#!forum/angular-dev
-[closing-issues]: https://help.github.com/articles/closing-issues-via-commit-messages/
+[Closure guide to i18n changes]: https://github.com/google/closure-library/wiki/Internationalization-%28i18n%29-changes-in-Closure-Library
 [coc]: https://github.com/angular/code-of-conduct/blob/master/CODE_OF_CONDUCT.md
-[commit-message-format]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#
-[contribute]: http://docs.angularjs.org/misc/contribute
-[contributing]: http://docs.angularjs.org/misc/contribute
+[Common Locale Data Repository (CLDR)]: http://cldr.unicode.org
 [corporate-cla]: http://code.google.com/legal/corporate-cla-v1.0.html
-[dev-doc]: https://docs.angularjs.org/guide
+[developers]: DEVELOPERS.md
+[developers.commits]: DEVELOPERS.md#commits
+[developers.documentation]: DEVELOPERS.md#documentation
+[developers.rules]: DEVELOPERS.md#rules
+[developers.setup]: DEVELOPERS.md#setup
+[developers.tests-e2e]: DEVELOPERS.md#e2e-tests
+[developers.tests-unit]: DEVELOPERS.md#unit-tests
+[github-issues]: https://github.com/angular/angular.js/issues
+[github-new-issue]: https://github.com/angular/angular.js/issues/new
 [github]: https://github.com/angular/angular.js
 [gitter]: https://gitter.im/angular/angular.js
+[Google Closure I18N library]: https://github.com/google/closure-library/tree/master/closure/goog/i18n
 [groups]: https://groups.google.com/forum/?fromgroups#!forum/angular
 [individual-cla]: http://code.google.com/legal/individual-cla-v1.0.html
 [irc]: http://webchat.freenode.net/?channels=angularjs&uio=d4
-[js-style-guide]: https://google.github.io/styleguide/javascriptguide.xml
 [jsfiddle]: http://jsfiddle.net/
-[list]: https://groups.google.com/forum/?fromgroups#!forum/angular
-[ngDocs]: https://github.com/angular/angular.js/wiki/Writing-AngularJS-Documentation
+[karma-browserstack]: https://github.com/karma-runner/karma-browserstack-launcher
+[karma-saucelabs]: https://github.com/karma-runner/karma-sauce-launcher
 [plunker]: http://plnkr.co/edit
 [stackoverflow]: http://stackoverflow.com/questions/tagged/angularjs
-[unit-testing]: https://docs.angularjs.org/guide/unit-testing
-[Common Locale Data Repository (CLDR)]: http://cldr.unicode.org
-[Closure guide to i18n changes]: https://github.com/google/closure-library/wiki/Internationalization-%28i18n%29-changes-in-Closure-Library
 
 [![Analytics](https://ga-beacon.appspot.com/UA-8594346-11/angular.js/CONTRIBUTING.md?pixel)](https://github.com/igrigorik/ga-beacon)

DEVELOPERS.md

@@ -0,0 +1,486 @@
+# Developing AngularJS
+
+* [Development Setup](#setup)
+* [Coding Rules](#rules)
+* [Commit Message Guidelines](#commits)
+* [Writing Documentation](#documentation)
+
+## <a name="setup"> Development Setup
+
+This document describes how to set up your development environment to build and test AngularJS, and
+explains the basic mechanics of using `git`, `node`, `yarn`, `grunt`, and `bower`.
+
+### Installing Dependencies
+
+Before you can build AngularJS, you must install and configure the following dependencies on your
+machine:
+
+* [Git](http://git-scm.com/): The [Github Guide to
+  Installing Git][git-setup] is a good source of information.
+
+* [Node.js v6.x (LTS)](http://nodejs.org): We use Node to generate the documentation, run a
+  development web server, run tests, and generate distributable files. Depending on your system,
+  you can install Node either from source or as a pre-packaged bundle.
+
+  We recommend using [nvm](https://github.com/creationix/nvm) (or
+  [nvm-windows](https://github.com/coreybutler/nvm-windows))
+  to manage and install Node.js, which makes it easy to change the version of Node.js per project.
+
+* [Yarn](https://yarnpkg.com): We use Yarn to install our Node.js module dependencies
+  (rather than using npm). See the detailed [installation instructions][yarn-install].
+
+* [Java](http://www.java.com): We minify JavaScript using
+  [Closure Tools](https://developers.google.com/closure/), which require Java (version 7 or higher)
+  to be installed and included in your
+  [PATH](http://docs.oracle.com/javase/tutorial/essential/environment/paths.html) variable.
+
+* [Grunt](http://gruntjs.com): We use Grunt as our build system. We're using it as a local dependency,
+  but you can also add the grunt command-line tool globally (with `yarn global add grunt-cli`), which allows
+  you to leave out the `yarn` prefix for all our grunt commands.
+
+### Forking AngularJS on Github
+
+To contribute code to AngularJS, you must have a GitHub account so you can push code to your own
+fork of AngularJS and open Pull Requests in the [GitHub Repository][github].
+
+To create a Github account, follow the instructions [here](https://github.com/signup/free).
+Afterwards, go ahead and [fork](http://help.github.com/forking) the
+[main AngularJS repository][github].
+
+
+### Building AngularJS
+
+To build AngularJS, you clone the source code repository and use Grunt to generate the non-minified
+and minified AngularJS files:
+
+```shell
+# Clone your Github repository:
+git clone https://github.com/<github username>/angular.js.git
+
+# Go to the AngularJS directory:
+cd angular.js
+
+# Add the main AngularJS repository as an upstream remote to your repository:
+git remote add upstream "https://github.com/angular/angular.js.git"
+
+# Install node.js dependencies:
+yarn install
+
+# Build AngularJS (which will install `bower` dependencies automatically):
+yarn grunt package
+```
+
+**Note:** If you're using Windows, you must use an elevated command prompt (right click, run as
+Administrator). This is because `yarn grunt package` creates some symbolic links.
+
+The build output is in the `build` directory. It consists of the following files and
+directories:
+
+* `angular-<version>.zip` — The complete zip file, containing all of the release build
+artifacts.
+
+* `angular.js` / `angular.min.js` — The regular and minified core AngularJS script file.
+
+* `angular-*.js` / `angular-*.min.js` — All other AngularJS module script files.
+
+* `docs/` — A directory that contains a standalone version of the docs
+  (same as served in `docs.angularjs.org`).
+
+### <a name="local-server"></a> Running a Local Development Web Server
+
+To debug code, run end-to-end tests, and serve the docs, it is often useful to have a local
+HTTP server. For this purpose, we have made available a local web server based on Node.js.
+
+1. To start the web server, run:
+   ```shell
+   yarn grunt webserver
+   ```
+
+2. To access the local server, enter the following URL into your web browser:
+   ```text
+   http://localhost:8000/
+   ```
+   By default, it serves the contents of the AngularJS project directory.
+
+3. To access the locally served docs, visit this URL:
+   ```text
+   http://localhost:8000/build/docs/
+   ```
+
+### <a name="unit-tests"></a> Running the Unit Test Suite
+
+We write unit and integration tests with Jasmine and execute them with Karma. To run all of the
+tests once on Chrome run:
+
+```shell
+yarn grunt test:unit
+```
+
+To run the tests on other browsers (Chrome, ChromeCanary, Firefox and Safari are pre-configured) use:
+
+```shell
+yarn grunt test:unit --browsers=Chrome,Firefox
+```
+
+**Note:** there should be _no spaces between browsers_. `Chrome, Firefox` is INVALID.
+
+If you have a Saucelabs or Browserstack account, you can also run the unit tests on these services
+via our pre-defined customLaunchers.
+
+For example, to run the whole unit test suite:
+
+```shell
+# Browserstack
+yarn grunt test:unit --browsers=BS_Chrome,BS_Firefox,BS_Safari,BS_IE_9,BS_IE_10,BS_IE_11,BS_EDGE,BS_iOS_8,BS_iOS_9,BS_iOS_10
+# Saucelabs
+yarn grunt test:unit --browsers=BS_Chrome,BS_Firefox,BS_Safari,BS_IE_9,BS_IE_10,BS_IE_11,BS_EDGE,BS_iOS_8,BS_iOS_9,BS_iOS_10
+```
+
+Running these commands requires you to set up [Karma Browserstack][karma-browserstack] or
+[Karma-Saucelabs][karma-saucelabs], respectively.
+
+During development, however, it's more productive to continuously run unit tests every time the
+source or test files change. To execute tests in this mode run:
+
+1. To start the Karma server, capture Chrome browser and run unit tests, run:
+
+   ```shell
+   yarn grunt autotest
+   ```
+
+2. To capture more browsers, open this URL in the desired browser (URL might be different if you
+   have multiple instance of Karma running, read Karma's console output for the correct URL):
+
+   ```text
+   http://localhost:9876/
+   ```
+
+3. To re-run tests just change any source or test file.
+
+
+To learn more about all of the preconfigured Grunt tasks run:
+
+```shell
+yarn grunt --help
+```
+
+
+### <a name="e2e-tests"></a> Running the End-to-end Test Suite
+
+AngularJS's end to end tests are run with Protractor. Simply run:
+
+```shell
+yarn grunt test:e2e
+```
+
+This will start the webserver and run the tests on Chrome.
+
+## <a name="rules"></a> Coding Rules
+
+To ensure consistency throughout the source code, keep these rules in mind as you are working:
+
+* All features or bug fixes **must be tested** by one or more [specs][unit-testing].
+* All public API methods **must be documented** with ngdoc, an extended version of jsdoc (we added
+  support for markdown and templating via @ngdoc tag). To see how we document our APIs, please check
+  out the existing source code and see the section about [writing documentation](#documentation)
+* With the exceptions listed below, we follow the rules contained in
+  [Google's JavaScript Style Guide][js-style-guide]:
+    * **Do not use namespaces**: Instead,  wrap the entire AngularJS code base in an anonymous
+      closure and export our API explicitly rather than implicitly.
+    * Wrap all code at **100 characters**.
+    * Instead of complex inheritance hierarchies, we **prefer simple objects**. We use prototypal
+      inheritance only when absolutely necessary.
+    * We **love functions and closures** and, whenever possible, prefer them over objects.
+    * To write concise code that can be better minified, we **use aliases internally** that map to
+      the external API. See our existing code to see what we mean.
+    * We **don't go crazy with type annotations** for private internal APIs unless it's an internal
+      API that is used throughout AngularJS. The best guidance is to do what makes the most sense.
+
+### Specific topics
+
+#### Provider configuration
+
+When adding configuration (options) to [providers][docs.provider], we follow a special pattern.
+
+- for each option, add a `method` that ...
+  - works as a getter and returns the current value when called without argument
+  - works as a setter and returns itself for chaining when called with argument
+  - for boolean options, uses the naming scheme `<option>Enabled([enabled])`
+- non-primitive options (e.g. objects) should be copied or the properties assigned explicitly to a
+  new object so that the configuration cannot be changed during runtime.
+
+For a boolean config example, see [`$compileProvider#debugInfoEnabled`][code.debugInfoEnabled]
+
+For an object config example, see [`$location.html5Mode`][code.html5Mode]
+
+#### Throwing errors
+
+User-facing errors should be thrown with [`minErr`][code.minErr], a special error function that provides
+errors ids, templated error messages, and adds a link to a detailed error description.
+
+The `$compile:badrestrict` error is a good example for a well-defined `minErr`:
+[code][code.badrestrict] and [description][docs.badrestrict].
+
+
+## <a name="commits"></a> Git Commit Guidelines
+
+We have very precise rules over how our git commit messages can be formatted.  This leads to **more
+readable messages** that are easy to follow when looking through the **project history**.  But also,
+we use the git commit messages to **generate the AngularJS change log**.
+
+The commit message formatting can be added using a typical git workflow or through the use of a CLI
+wizard ([Commitizen](https://github.com/commitizen/cz-cli)). To use the wizard, run `yarn run commit`
+in your terminal after staging your changes in git.
+
+### Commit Message Format
+Each commit message consists of a **header**, a **body** and a **footer**.  The header has a special
+format that includes a **type**, a **scope** and a **subject**:
+
+```
+<type>(<scope>): <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+The **header** is mandatory and the **scope** of the header is optional.
+
+Any line of the commit message cannot be longer 100 characters! This allows the message to be easier
+to read on GitHub as well as in various git tools.
+
+### Revert
+If the commit reverts a previous commit, it should begin with `revert: `, followed by the header
+of the reverted commit.
+In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit
+being reverted.
+A commit with this format is automatically created by the [`git revert`][git-revert] command.
+
+### Type
+Must be one of the following:
+
+* **feat**: A new feature
+* **fix**: A bug fix
+* **docs**: Documentation only changes
+* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
+  semi-colons, etc)
+* **refactor**: A code change that neither fixes a bug nor adds a feature
+* **perf**: A code change that improves performance
+* **test**: Adding missing or correcting existing tests
+* **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
+  generation
+
+### Scope
+The scope could be anything specifying place of the commit change. For example `$location`,
+`$browser`, `$compile`, `$rootScope`, `ngHref`, `ngClick`, `ngView`, etc...
+
+You can use `*` when the change affects more than a single scope.
+
+### Subject
+The subject contains succinct description of the change:
+
+* use the imperative, present tense: "change" not "changed" nor "changes"
+* don't capitalize first letter
+* no dot (.) at the end
+
+### Body
+Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes".
+The body should include the motivation for the change and contrast this with previous behavior.
+
+### Footer
+The footer should contain any information about **Breaking Changes** and is also the place to
+[reference GitHub issues that this commit closes][closing-issues].
+
+**Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines.
+The rest of the commit message is then used for this.
+
+A detailed explanation can be found in this [document][commit-message-format].
+
+## <a name="documentation"></a> Writing Documentation
+
+The AngularJS project uses a form of [jsdoc](http://usejsdoc.org/) called ngdoc for all of its code
+documentation.
+
+This means that all the docs are stored inline in the source code and so are kept in sync as it
+changes.
+
+There is also extra content (the developer guide, error pages, the tutorial,
+and misceallenous pages) that live inside the AngularJS repository as markdown files.
+
+This means that since we generate the documentation from the source code, we can easily provide
+version-specific documentation by simply checking out a version of AngularJS and running the build.
+
+Extracting the source code documentation, processing and building the docs is handled by the
+documentation generation tool [Dgeni][dgeni].
+
+### Building and viewing the docs locally
+The docs can be built from scratch using grunt:
+
+```shell
+yarn grunt docs
+```
+
+This defers the doc-building task to `gulp`.
+
+Note that the docs app is using the local build files to run. This means you might first have to run
+the build:
+
+```shell
+yarn grunt build
+```
+
+(This is also necessary if you are making changes to minErrors).
+
+To view the docs, see [Running a Local Development Web Server](#local-server).
+
+### Writing jsdoc
+The ngdoc utility has basic support for many of the standard jsdoc directives.  But in particular it
+is interested in the following block tags:
+
+* `@name name` - the name of the ngdoc document
+* `@param {type} name description` - describes a parameter of a function
+* `@returns {type} description` - describes what a function returns
+* `@requires` - normally indicates that a JavaScript module is required; in an Angular service it is
+  used to describe what other services this service relies on
+* `@property` - describes a property of an object
+* `@description` - used to provide a description of a component in markdown
+* `@link` - specifies a link to a URL or a type in the API reference.
+  Links to the API have the following structure:
+
+  * the module namespace, followed by `.` (optional, default `ng`)
+  * the `@ngdoc` type (see below), followed by `:` (optional, automatically inferred)
+  * the name
+  * the method, property, or anchor (optional)
+  * the display name
+
+  For example: `{@link ng.type:$rootScope.Scope#$new Scope.$new()}`.
+
+* `@example` - specifies an example. This can be a simple code block, or a
+  [runnable example](#the-example-tag).
+* `@deprecated` - specifies that the following code is deprecated and should not be used.
+  In The AngularJS docs, there are two specific patterns which can be used to further describe
+  the deprecation: `sinceVersion="<version>"` and `removeVersion="<version>"`
+
+The `type` in `@param` and `@returns` must be wrapped in `{}` curly braces, e.g. `{Object|Array}`.
+Parameters can be made optional by *either* appending a `=` to the type, e.g. `{Object=}`, *or* by
+putting the `[name]` in square brackets.
+Default values are only possible with the second syntax by appending `=<value>` to the parameter
+name, e.g. `@param {boolean} [ownPropsOnly=false]`.
+
+Descriptions can contain markdown formatting.
+
+#### AngularJS-specific jsdoc directives
+
+In addition to the standard jsdoc tags, there are a number that are specific to the Angular
+code-base:
+
+* `@ngdoc` - specifies the type of thing being documented. See below for more detail.
+* `@eventType emit|broadcast` - specifies whether the event is emitted or broadcast
+* `@usage` - shows how to use a `function` or `directive`. Is usually automatically generated.
+* `@knownIssue` - adds info about known quirks, problems, or limitations with the API, and possibly,
+  workarounds. This section is not for bugs.
+
+The following are specific to directives:
+
+* `@animations` - specifies the animations a directive supports
+* `@multiElement` - specifies if a directive can span over multiple elements
+* `@priority` - specifies a directive's priority
+* `@restrict` - is extracted to show the usage of a directive. For example, for [E]lement,
+  [A]ttribute, and [C]lass, use `@restrict ECA`
+* `@scope` - specifies that a directive will create a new scope
+
+### The `@ngdoc` Directive
+This directive helps to specify the template used to render the item being documented.  For instance,
+a directive would have different properties to a filter and so would be documented differently.  The
+commonly used types are:
+
+* `overview` - a general page (guide, api index)
+* `provider` - AngularJS provider, such as `$compileProvider` or `$httpProvider`.
+* `service` - injectable AngularJS service, such as `$compile` or `$http`.
+* `object` - well defined object (often exposed as a service)
+* `function` - function that will be available to other methods (such as a helper function within
+  the ng module)
+* `method` - method on an object/service/controller
+* `property` - property on an object/service/controller
+* `event` -  AngularJS event that will propagate through the `$scope` tree.
+* `directive` - AngularJS  directive
+* `filter` - AngularJS filter
+* `error` - minErr error description
+
+### General documentation with Markdown
+
+Any text in tags can contain markdown syntax for formatting. Generally, you can use any markdown
+feature.
+
+#### Headings
+
+Only use *h2* headings and lower, as the page title is set in *h1*. Also make sure you follow the
+heading hierarchy. This ensures correct table of contents are created.
+
+#### Code blocks
+In line code can be specified by enclosing the code in back-ticks (\`).
+A block of multi-line code can be enclosed in triple back-ticks (\`\`\`) but it is formatted better
+if it is enclosed in &lt;pre&gt;...&lt;/pre&gt; tags and the code lines themselves are indented.
+
+### Writing runnable (live) examples and e2e tests
+It is possible to embed examples in the documentation along with appropriate e2e tests. These
+examples and scenarios will be converted to runnable code within the documentation.  So it is
+important that they work correctly.  To ensure this, all these e2e scenarios are run as part of the
+automated Travis tests.
+
+If you are adding an example with an e2e test, you should [run the test locally](#e2e-tests) first
+to ensure it passes. You can change `it(...)` to `fit(...)` to run only your test,
+but make sure you change it back to `it(...)` before committing.
+
+#### The `<example>` tag
+This tag identifies a block of HTML that will define a runnable example. It can take the following
+attributes:
+
+* `animations` - if set to `true` then this example uses ngAnimate.
+* `deps` - Semicolon-separated list of additional angular module files to be loaded,
+  e.g. `angular-animate.js`
+* `name` - every example should have a name. It should start with the component, e.g directive name,
+  and not contain whitespace
+* `module` - the name of the app module as defined in the example's JavaScript
+
+Within this tag we provide `<file>` tags that specify what files contain the example code.
+
+```
+<example
+  module="angularAppModule"
+  name="exampleName"
+  deps="angular-animate.js;angular-route.js"
+  animations="true">
+  ...
+  <file name="index.html">...</file>
+  <file name="script.js">...</file>
+  <file name="animations.css">...</file>
+  <file name="protractor.js">...</file>
+  ...
+</example>
+```
+
+You can see an example of a well-defined example [in the `ngRepeat` documentation][code.ngRepeat-example].
+
+[closing-issues]: https://help.github.com/articles/closing-issues-via-commit-messages/
+[Closure guide to i18n changes]: https://github.com/google/closure-library/wiki/Internationalization-%28i18n%29-changes-in-Closure-Library
+[code.badrestrict]: https://github.com/angular/angular.js/blob/202f1809ad14827a6ac6a125157c605d65e0b551/src/ng/compile.js#L1107-L1110
+[code.debugInfoEnabled]: https://github.com/angular/angular.js/blob/32fbb2e78f53d765fbb170f7cf99e42e072d363b/src/ng/compile.js#L1378-L1413
+[code.html5Mode]: https://github.com/angular/angular.js/blob/202f1809ad14827a6ac6a125157c605d65e0b551/src/ng/location.js#L752-L797
+[code.minErr]: https://github.com/angular/angular.js/blob/202f1809ad14827a6ac6a125157c605d65e0b551/src/minErr.js#L53-L113
+[code.ngRepeat-example]: https://github.com/angular/angular.js/blob/0822d34b10ea0371c260c80a1486a4d508ea5a91/src/ng/directive/ngRepeat.js#L249-L340
+[commit-message-format]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#
+[Common Locale Data Repository (CLDR)]: http://cldr.unicode.org
+[corporate-cla]: http://code.google.com/legal/corporate-cla-v1.0.html
+[dgeni]: https://github.com/angular/dgeni
+[docs.badrestrict]: docs/content/error/$compile/badrestrict.ngdoc
+[docs.provider]: https://code.angularjs.org/snapshot/docs/api/auto/service/$provide#provider
+[git-revert]: https://git-scm.com/docs/git-revert
+[git-setup]: https://help.github.com/articles/set-up-git
+[github-issues]: https://github.com/angular/angular.js/issues
+[github]: https://github.com/angular/angular.js
+[js-style-guide]: https://google.github.io/styleguide/javascriptguide.xml
+[karma-browserstack]: https://github.com/karma-runner/karma-browserstack-launcher
+[karma-saucelabs]: https://github.com/karma-runner/karma-sauce-launcher
+[unit-testing]: https://docs.angularjs.org/guide/unit-testing
+[yarn-install]: https://yarnpkg.com/en/docs/install

Gruntfile.js

@@ -63,7 +63,11 @@ module.exports = function(grunt) {
   NG_VERSION.cdn = versionInfo.cdnVersion;
   var dist = 'angular-' + NG_VERSION.full;
 
-  var deployVersion = NG_VERSION.isSnapshot ? 'snapshot' : NG_VERSION.full;
+  var deployVersion = NG_VERSION.full;
+
+  if (NG_VERSION.isSnapshot) {
+    deployVersion = NG_VERSION.distTag === 'latest' ? 'snapshot-stable' : 'snapshot';
+  }
 
   if (versionInfo.cdnVersion == null) {
     throw new Error('Unable to read CDN version, are you offline or has the CDN not been properly pushed?\n' +
@@ -312,7 +316,29 @@ module.exports = function(grunt) {
     copy: {
       i18n: {
         files: [
-          { src: 'src/ngLocale/**', dest: 'build/i18n/', expand: true, flatten: true }
+          {
+            src: 'src/ngLocale/**',
+            dest: 'build/i18n/',
+            expand: true,
+            flatten: true
+          }
+        ]
+      },
+      deployFirebaseDocs: {
+        files: [
+          // The source files are needed by the embedded examples in the docs app.
+          {
+            src: 'build/angular*.{js.map,min.js}',
+            dest: 'uploadDocs/',
+            expand: true,
+            flatten: true
+          },
+          {
+            cwd: 'build/docs',
+            src: '**',
+            dest: 'uploadDocs/',
+            expand: true
+          }
         ]
       }
     },
@@ -327,14 +353,14 @@ module.exports = function(grunt) {
         dot: true,
         dest: dist + '/'
       },
-      firebaseCodeDeploy: {
+      deployFirebaseCode: {
         options: {
           mode: 'gzip'
         },
         src: ['**'],
         cwd: 'build',
         expand: true,
-        dest: 'upload/' + deployVersion + '/'
+        dest: 'uploadCode/' + deployVersion + '/'
       }
     },
 
@@ -428,7 +454,7 @@ module.exports = function(grunt) {
     'collect-errors',
     'write',
     'docs',
-    'copy',
+    'copy:i18n',
     'compress:build'
   ]);
   grunt.registerTask('ci-checks', [
@@ -436,6 +462,11 @@ module.exports = function(grunt) {
     'merge-conflict',
     'eslint'
   ]);
+  grunt.registerTask('prepareFirebaseDeploy', [
+    'package',
+    'compress:deployFirebaseCode',
+    'copy:deployFirebaseDocs'
+  ]);
   grunt.registerTask('default', ['package']);
 };
 

README.md

@@ -16,35 +16,27 @@ piece of cake. Best of all? It makes development fun!
 * Tutorial: https://docs.angularjs.org/tutorial
 * API Docs: https://docs.angularjs.org/api
 * Developer Guide: https://docs.angularjs.org/guide
-* Contribution guidelines: [CONTRIBUTING.md](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md)
+* Contribution guidelines: [CONTRIBUTING.md](CONTRIBUTING.md)
+* Core Development: [DEVELOPERS.md](DEVELOPERS.md)
 * Dashboard: https://dashboard.angularjs.org
 
 ##### Looking for Angular 2? Go here: https://github.com/angular/angular
 
-Building AngularJS
----------
-[Once you have set up your environment](https://docs.angularjs.org/misc/contribute), just run:
+Documentation
+--------------------
+Go to https://docs.angularjs.org
 
-    grunt package
-
-
-Running tests
--------------
-To execute all unit tests, use:
-
-    grunt test:unit
-
-To execute end-to-end (e2e) tests, use:
-
-    grunt package
-    grunt test:e2e
-
-To learn more about the grunt tasks, run `grunt --help`
-
-Contribute & Develop
+Contribute
 --------------------
 
-We've set up a separate document for our [contribution guidelines](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md).
+We've set up a separate document for our
+[contribution guidelines](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md).
+
+Develop
+--------------------
+
+We've set up a separate document for
+[developers](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md).
 
 
 [![Analytics](https://ga-beacon.appspot.com/UA-8594346-11/angular.js/README.md?pixel)](https://github.com/igrigorik/ga-beacon)

docs/app/assets/css/docs.css

@@ -905,6 +905,35 @@ iframe[name="example-anchoringExample"] {
   background-color: inherit;
 }
 
+toc-container {
+  display: block;
+  margin: 15px 10px;
+}
+
+toc-container b {
+  text-transform: uppercase;
+}
+
+toc-container .btn {
+  padding: 3px 6px;
+  font-size: 13px;
+  margin-left: 5px;
+}
+
+toc-container > div > toc-tree ul {
+  list-style: none;
+  padding-left: 15px;
+  padding-bottom: 2px;
+}
+
+toc-container > div > toc-tree > ul {
+  padding-left: 0;
+}
+
+toc-container > div > toc-tree > ul > li > toc-tree > ul > li toc-tree > ul li {
+  font-size: 13px;
+}
+
 @media handheld and (max-width:800px), screen and (max-device-width:800px), screen and (max-width:800px) {
   .navbar {
     min-height: auto;

docs/app/e2e/api-docs/api-pages.scenario.js

@@ -1,51 +1,48 @@
 'use strict';
 
-describe('doc.angularjs.org', function() {
+describe('API pages', function() {
 
-  describe('API pages', function() {
+  it('should display links to code on GitHub', function() {
+    browser.get('build/docs/index.html#!/api/ng/service/$http');
+    expect(element(by.css('.improve-docs')).getAttribute('href')).toMatch(/https?:\/\/github\.com\/angular\/angular\.js\/edit\/.+\/src\/ng\/http\.js/);
 
-    it('should display links to code on GitHub', function() {
-      browser.get('build/docs/index.html#!/api/ng/service/$http');
-      expect(element(by.css('.improve-docs')).getAttribute('href')).toMatch(/https?:\/\/github\.com\/angular\/angular\.js\/edit\/.+\/src\/ng\/http\.js/);
+    browser.get('build/docs/index.html#!/api/ng/service/$http');
+    expect(element(by.css('.view-source')).getAttribute('href')).toMatch(/https?:\/\/github\.com\/angular\/angular\.js\/tree\/.+\/src\/ng\/http\.js#L\d+/);
+  });
 
-      browser.get('build/docs/index.html#!/api/ng/service/$http');
-      expect(element(by.css('.view-source')).getAttribute('href')).toMatch(/https?:\/\/github\.com\/angular\/angular\.js\/tree\/.+\/src\/ng\/http\.js#L\d+/);
-    });
+  it('should change the page content when clicking a link to a service', function() {
+    browser.get('build/docs/index.html');
 
-    it('should change the page content when clicking a link to a service', function() {
-      browser.get('build/docs/index.html');
+    var ngBindLink = element(by.css('.definition-table td a[href="api/ng/directive/ngClick"]'));
+    ngBindLink.click();
 
-      var ngBindLink = element(by.css('.definition-table td a[href="api/ng/directive/ngClick"]'));
-      ngBindLink.click();
-
-      var mainHeader = element(by.css('.main-body h1 '));
-      expect(mainHeader.getText()).toEqual('ngClick');
-    });
+    var mainHeader = element(by.css('.main-body h1 '));
+    expect(mainHeader.getText()).toEqual('ngClick');
+  });
 
 
-    it('should show the functioning input directive example', function() {
-      browser.get('build/docs/index.html#!/api/ng/directive/input');
+  it('should show the functioning input directive example', function() {
+    browser.get('build/docs/index.html#!/api/ng/directive/input');
 
-      // Ensure that the page is loaded before trying to switch frames.
-      browser.waitForAngular();
+    // Ensure that the page is loaded before trying to switch frames.
+    browser.waitForAngular();
 
-      browser.switchTo().frame('example-input-directive');
+    browser.switchTo().frame('example-input-directive');
 
-      var nameInput = element(by.model('user.name'));
-      nameInput.sendKeys('!!!');
+    var nameInput = element(by.model('user.name'));
+    nameInput.sendKeys('!!!');
 
-      var code = element.all(by.css('tt')).first();
-      expect(code.getText()).toContain('guest!!!');
-    });
+    var code = element.all(by.css('tt')).first();
+    expect(code.getText()).toContain('guest!!!');
+  });
 
-    it('should trim indentation from code blocks', function() {
-      browser.get('build/docs/index.html#!/api/ng/type/$rootScope.Scope');
+  it('should trim indentation from code blocks', function() {
+    browser.get('build/docs/index.html#!/api/ng/type/$rootScope.Scope');
 
-      var codeBlocks = element.all(by.css('pre > code.lang-js'));
-      codeBlocks.each(function(codeBlock) {
-        var firstSpan = codeBlock.all(by.css('span')).first();
-        expect(firstSpan.getText()).not.toMatch(/^\W+$/);
-      });
+    var codeBlocks = element.all(by.css('pre > code.lang-js'));
+    codeBlocks.each(function(codeBlock) {
+      var firstSpan = codeBlock.all(by.css('span')).first();
+      expect(firstSpan.getText()).not.toMatch(/^\W+$/);
     });
   });
 });

docs/app/e2e/api-docs/directive-pages.scenario.js

@@ -0,0 +1,58 @@
+'use strict';
+
+describe('directives', function() {
+
+  describe('parameter section', function() {
+
+    it('should show the directive name only if it is a param (attribute) with a value', function() {
+      browser.get('build/docs/index.html#!/api/ng/directive/ngInclude');
+      expect(getParamNames().getText()).toContain('ngInclude | src');
+
+      browser.get('build/docs/index.html#!/api/ngRoute/directive/ngView');
+      expect(getParamNames().getText()).not.toContain('ngView');
+    });
+  });
+
+  describe('usage section', function() {
+
+    it('should show the directive name if it is a param (attribute) with a value', function() {
+      browser.get('build/docs/index.html#!/api/ng/directive/ngInclude');
+
+      expect(getUsageAs('element', 'ng-include').isPresent()).toBe(true);
+      expect(getUsageAs('attribute', 'ng-include').isPresent()).toBe(true);
+      expect(getUsageAs('CSS class', 'ng-include').isPresent()).toBe(true);
+    });
+
+    it('should show the directive name if it is a void param (attribute)', function() {
+      browser.get('build/docs/index.html#!/api/ngRoute/directive/ngView');
+
+      expect(getUsageAs('element', 'ng-view').isPresent()).toBe(true);
+      expect(getUsageAs('attribute', 'ng-view').isPresent()).toBe(true);
+      expect(getUsageAs('CSS class', 'ng-view').isPresent()).toBe(true);
+    });
+  });
+});
+
+function getParamNames() {
+  var argsSection = element(by.className('input-arguments'));
+
+  var paramNames = argsSection.all(by.css('tr td:nth-child(1)'));
+
+  return paramNames;
+}
+
+// Based on the type of directive usage, the directive name will show up in the code block
+// with a specific class
+var typeClassMap = {
+  element: 'tag',
+  attribute: 'atn',
+  'CSS class': 'atv'
+};
+
+function getUsageAs(type, directiveName) {
+  var usage = element(by.className('usage'));
+
+  var as = usage.element(by.cssContainingText('li', 'as ' + type));
+
+  return as.element(by.cssContainingText('span.' + typeClassMap[type], directiveName));
+}

docs/app/e2e/app.scenario.js

@@ -49,6 +49,25 @@ describe('docs.angularjs.org', function() {
     });
 
 
+    it('should include the files for the embedded examples from the same domain', function() {
+      browser.get('build/docs/index-production.html#!api/ng/directive/ngClick');
+
+      var origin = browser.executeScript('return document.location.origin;');
+
+      var exampleIFrame = element(by.name('example-ng-click'));
+
+      // This is technically an implementation detail, but if this changes, then there's a good
+      // chance the deployment process changed
+      expect(exampleIFrame.getAttribute('src')).toContain('examples/example-ng-click/index.html');
+
+      browser.switchTo().frame('example-ng-click');
+
+      var scriptEl = element(by.tagName('script'));
+
+      // Ensure the included file is from the same domain
+      expect(scriptEl.getAttribute('src')).toContain(origin);
+    });
+
 
     it('should be resilient to trailing slashes', function() {
       browser.get('build/docs/index-production.html#!/api/ng/function/angular.noop/');

docs/app/e2e/table-of-contents.scenario.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * This scenario checks the presence of the table of contents for a sample of pages - API and guide.
+ * The expectations are kept vague so that they can be easily adjusted when the docs change.
+ */
+
+describe('table of contents', function() {
+
+  it('on provider pages', function() {
+    browser.get('build/docs/index.html#!/api/ng/provider/$interpolateProvider');
+
+    var toc = element.all(by.css('toc-container > div > toc-tree'));
+    toc.getText().then(function(text) {
+      expect(text.join('')).toContain('Overview');
+      expect(text.join('')).toContain('Methods');
+    });
+
+    var tocFirstLevel = element.all(by.css('toc-container > div > toc-tree > ul > li'));
+
+    tocFirstLevel.then(function(match) {
+      expect(match.length).toBe(3);
+
+      expect(match[1].all(by.css('li')).count()).toBe(2);
+    });
+
+  });
+
+  it('on service pages', function() {
+    browser.get('build/docs/index.html#!/api/ng/service/$controller');
+
+    var toc = element.all(by.css('toc-container > div > toc-tree'));
+    toc.getText().then(function(text) {
+      expect(text.join('')).toContain('Overview');
+      expect(text.join('')).toContain('Usage');
+    });
+
+    var tocFirstLevel = element.all(by.css('toc-container > div > toc-tree > ul > li'));
+
+    tocFirstLevel.then(function(match) {
+      expect(match.length).toBe(3);
+
+      expect(match[2].all(by.css('li')).count()).toBe(2);
+    });
+  });
+
+  it('on directive pages', function() {
+    browser.get('build/docs/index.html#!/api/ng/directive/input');
+
+    var toc = element.all(by.css('toc-container > div > toc-tree'));
+    toc.getText().then(function(text) {
+      expect(text.join('')).toContain('Overview');
+      expect(text.join('')).toContain('Usage');
+      expect(text.join('')).toContain('Directive Info');
+    });
+
+    var tocFirstLevel = element.all(by.css('toc-container > div > toc-tree > ul > li'));
+
+    tocFirstLevel.then(function(match) {
+      expect(match.length).toBe(4);
+
+      expect(match[2].all(by.css('li')).count()).toBe(1);
+    });
+  });
+
+  it('on function pages', function() {
+    browser.get('build/docs/index.html#!/api/ng/function/angular.bind');
+
+    var toc = element.all(by.css('toc-container > div > toc-tree'));
+    toc.getText().then(function(text) {
+      expect(text.join('')).toContain('Overview');
+      expect(text.join('')).toContain('Usage');
+    });
+
+    var tocFirstLevel = element.all(by.css('toc-container > div > toc-tree > ul > li'));
+
+    tocFirstLevel.then(function(match) {
+      expect(match.length).toBe(2);
+
+      expect(match[1].all(by.css('li')).count()).toBe(2);
+    });
+  });
+
+  it('on type pages', function() {
+    browser.get('build/docs/index.html#!/api/ng/type/ModelOptions');
+
+    var toc = element.all(by.css('toc-container > div > toc-tree'));
+    toc.getText().then(function(text) {
+      expect(text.join('')).toContain('Overview');
+      expect(text.join('')).toContain('Methods');
+    });
+
+    var tocFirstLevel = element.all(by.css('toc-container > div > toc-tree > ul > li'));
+
+    tocFirstLevel.then(function(match) {
+      expect(match.length).toBe(2);
+
+      expect(match[1].all(by.css('li')).count()).toBe(2);
+    });
+  });
+
+  it('on filter pages', function() {
+    browser.get('build/docs/index.html#!/api/ng/filter/date');
+
+    var toc = element.all(by.css('toc-container > div > toc-tree'));
+    toc.getText().then(function(text) {
+      expect(text.join('')).toContain('Overview');
+      expect(text.join('')).toContain('Usage');
+    });
+
+    var tocFirstLevel = element.all(by.css('toc-container > div > toc-tree > ul > li'));
+
+    tocFirstLevel.then(function(match) {
+      expect(match.length).toBe(3);
+
+      expect(match[1].all(by.css('li')).count()).toBe(2);
+    });
+  });
+
+  it('on guide pages', function() {
+    browser.get('build/docs/index.html#!/guide/services');
+    var tocFirstLevel = element.all(by.css('toc-container > div > toc-tree > ul > li'));
+
+    tocFirstLevel.then(function(match) {
+      expect(match.length).toBe(5);
+
+      expect(match[1].all(by.css('li')).count()).toBe(3);
+    });
+  });
+});

docs/app/src/app.js

@@ -14,7 +14,6 @@ angular.module('docsApp', [
   'search',
   'tutorials',
   'versions',
-  'deployment',
   'ui.bootstrap.dropdown'
 ])
 

docs/app/src/directives.js

@@ -1,7 +1,8 @@
 'use strict';
 
-angular.module('directives', [])
+var directivesModule = angular.module('directives', []);
 
+directivesModule
 /**
  * backToTop Directive
  * @param  {Function} $anchorScroll
@@ -47,4 +48,133 @@ angular.module('directives', [])
       }
     }
   };
-});
+})
+
+.directive('tocCollector', ['$rootScope', function($rootScope) {
+  return {
+    controller: ['$element', function($element) {
+      /* eslint-disable no-invalid-this */
+      var ctrl = this;
+
+      $rootScope.$on('$includeContentRequested', function() {
+        ctrl.hs = [];
+        ctrl.root = [];
+      });
+
+      this.hs = [];
+      this.root = [];
+      this.element = $element;
+
+      this.register = function(h) {
+        var previousLevel;
+
+        for (var i = ctrl.hs.length - 1; i >= 0; i--) {
+          if (ctrl.hs[i].level === (h.level - 1)) {
+            previousLevel = ctrl.hs[i];
+            break;
+          }
+        }
+
+        if (previousLevel) {
+          previousLevel.children.push(h);
+        } else {
+          this.root.push(h);
+        }
+
+        ctrl.hs.push(h);
+        /* eslint-enable no-invalid-this */
+      };
+    }]
+  };
+}])
+
+.component('tocTree', {
+  template: '<ul>' +
+      '<li ng-repeat="item in $ctrl.items">' +
+        '<a ng-href="#{{item.fragment}}">{{item.title}}</a>' +
+        '<toc-tree ng-if="::item.children.length > 0" items="item.children"></toc-tree>' +
+      '</li>' +
+    '</ul>',
+  bindings: {
+    items: '<'
+  }
+})
+.directive('tocContainer', function() {
+  return {
+    scope: true,
+    restrict: 'E',
+    require: {
+      tocContainer: '',
+      tocCollector: '^^'
+    },
+    controller: function() {
+      this.showToc = true;
+      this.items = [];
+    },
+    controllerAs: '$ctrl',
+    link: function(scope, element, attrs, ctrls) {
+      ctrls.tocContainer.items = ctrls.tocCollector.root;
+    },
+    template: '<div ng-if="::$ctrl.items.length > 1">' +
+      '<b>Contents</b>' +
+      '<button class="btn" ng-click="$ctrl.showToc = !$ctrl.showToc">{{$ctrl.showToc ? \'Hide\' : \'Show\'}}</button><br>' +
+      '<toc-tree items="$ctrl.items" ng-show="$ctrl.showToc"></toc-tree>' +
+      '</div>'
+  };
+})
+.directive('header', function() {
+  return {
+    restrict: 'E',
+    controller: ['$element', function($element) {
+      // eslint-disable-next-line no-invalid-this
+      this.element = $element;
+    }]
+  };
+})
+.directive('h1', ['$compile', function($compile) {
+  return {
+    restrict: 'E',
+    require: {
+      tocCollector: '^^?',
+      header: '^^?'
+    },
+    link: function(scope, element, attrs, ctrls) {
+      if (!ctrls.tocCollector) return;
+
+      var tocContainer = angular.element('<toc-container></toc-container>');
+      var containerElement = ctrls.header ? ctrls.header.element : element;
+
+      containerElement.after(tocContainer);
+      $compile(tocContainer)(scope);
+    }
+  };
+}]);
+
+for (var i = 2; i <= 5; i++) {
+  registerHDirective(i);
+}
+
+function registerHDirective(i) {
+  directivesModule.directive('h' + i, function() {
+    return {
+      restrict: 'E',
+      require: {
+        'tocCollector': '^^?'
+      },
+      link: function(scope, element, attrs, ctrls) {
+        var toc = ctrls.tocCollector;
+
+        if (!toc || !attrs.id) return;
+
+        toc.register({
+          level: i,
+          fragment: attrs.id,
+          title: element.text(),
+          children: []
+        });
+
+      }
+    };
+  });
+}
+

docs/app/src/examples.js

@@ -18,13 +18,7 @@ angular.module('examples', [])
   return {
     restrict: 'C',
     scope : true,
-    controller : ['$scope', 'DEPLOYMENT', function($scope, DEPLOYMENT) {
-      var exampleIndexFile = (DEPLOYMENT === 'default' ? 'index' : 'index-' + DEPLOYMENT) + '.html';
-
-      $scope.getExampleIndex = function(basePath) {
-        return basePath + '/' + exampleIndexFile;
-      };
-
+    controller : ['$scope', function($scope) {
       $scope.setTab = function(index) {
         var tab = $scope.tabs[index];
         $scope.activeTabIndex = index;

docs/app/src/search.js

@@ -67,6 +67,12 @@ angular.module('search', [])
     clearResults();
     $scope.q = '';
   };
+
+  $scope.handleResultClicked = function($event) {
+    if ($event.which === 1 && !$event.ctrlKey && !$event.metaKey) {
+      $scope.hideResults();
+    }
+  };
 }])
 
 

docs/app/src/versions.js

@@ -12,10 +12,16 @@ angular.module('versions', ['currentVersionData', 'allVersionsData'])
             /** @this VersionPickerController */
             function VersionPickerController($location, $window, CURRENT_NG_VERSION, ALL_NG_VERSIONS) {
 
-      var versionStr = CURRENT_NG_VERSION.isSnapshot ? 'snapshot' : CURRENT_NG_VERSION.version;
+      var versionStr = CURRENT_NG_VERSION.version;
+
+      if (CURRENT_NG_VERSION.isSnapshot) {
+        versionStr = CURRENT_NG_VERSION.distTag === 'latest' ? 'snapshot-stable' : 'snapshot';
+      }
 
       this.versions  = ALL_NG_VERSIONS;
-      this.selectedVersion = find(ALL_NG_VERSIONS, function(value) { return value.version.version === versionStr; });
+      this.selectedVersion = find(ALL_NG_VERSIONS, function(value) {
+        return value.version.version === versionStr;
+      });
 
       this.jumpToDocsVersion = function(value) {
         var currentPagePath = $location.path().replace(/\/$/, '');

docs/app/test/directivesSpec.js

@@ -1,40 +1,50 @@
 'use strict';
 
-describe('code', function() {
-  var prettyPrintOne, oldPP;
+describe('directives', function() {
   var compile, scope;
 
-  var any = jasmine.any;
 
   beforeEach(module('directives'));
 
-  beforeEach(inject(function($rootScope, $compile) {
-    // Provide stub for pretty print function
-    oldPP = window.prettyPrintOne;
-    prettyPrintOne = window.prettyPrintOne = jasmine.createSpy();
+  beforeEach(module(function($compileProvider) {
+    $compileProvider.debugInfoEnabled(false);
+  }));
 
+  beforeEach(inject(function($rootScope, $compile) {
     scope = $rootScope.$new();
     compile = $compile;
   }));
 
-  afterEach(function() {
-    window.prettyPrintOne = oldPP;
-  });
+  describe('code', function() {
+    var prettyPrintOne, oldPP;
+    var any = jasmine.any;
+
+    beforeEach(function() {
+      // Provide stub for pretty print function
+      oldPP = window.prettyPrintOne;
+      prettyPrintOne = window.prettyPrintOne = jasmine.createSpy();
+    });
+
+    afterEach(function() {
+      window.prettyPrintOne = oldPP;
+    });
 
 
-  it('should pretty print innerHTML', function() {
-    compile('<code>var x;</code>')(scope);
-    expect(prettyPrintOne).toHaveBeenCalledWith('var x;', null, false);
+    it('should pretty print innerHTML', function() {
+      compile('<code>var x;</code>')(scope);
+      expect(prettyPrintOne).toHaveBeenCalledWith('var x;', null, false);
+    });
+
+    it('should allow language declaration', function() {
+      compile('<code class="lang-javascript"></code>')(scope);
+      expect(prettyPrintOne).toHaveBeenCalledWith(any(String), 'javascript', false);
+    });
+
+    it('supports allow line numbers', function() {
+      compile('<code class="linenum"></code>')(scope);
+      expect(prettyPrintOne).toHaveBeenCalledWith(any(String), null, true);
+    });
   });
 
-  it('should allow language declaration', function() {
-    compile('<code class="lang-javascript"></code>')(scope);
-    expect(prettyPrintOne).toHaveBeenCalledWith(any(String), 'javascript', false);
-  });
-
-  it('supports allow line numbers', function() {
-    compile('<code class="linenum"></code>')(scope);
-    expect(prettyPrintOne).toHaveBeenCalledWith(any(String), null, true);
-  });
 });
 

docs/config/index.js

@@ -112,10 +112,6 @@ module.exports = new Package('angularjs', [
     docTypes: ['indexPage'],
     pathTemplate: '.',
     outputPathTemplate: '${id}.html'
-  }, {
-    docTypes: ['deploymentData'],
-    pathTemplate: '.',
-    outputPathTemplate: 'js/${id}.js'
   });
 
   computePathsProcessor.pathTemplates.push({
@@ -129,14 +125,8 @@ module.exports = new Package('angularjs', [
     outputPathTemplate: 'partials/${area}/${moduleName}/${groupType}.html'
   });
 
-  computePathsProcessor.pathTemplates.push({
-    docTypes: ['example'],
-    pathTemplate: 'examples/${example.id}',
-    outputPathTemplate: 'examples/${example.id}/index${deploymentQualifier}.html'
-  });
-
   computeIdsProcessor.idTemplates.push({
-    docTypes: ['overview', 'tutorial', 'e2e-test', 'indexPage', 'deploymentData'],
+    docTypes: ['overview', 'tutorial', 'e2e-test', 'indexPage'],
     getId: function(doc) { return doc.fileInfo.baseName; },
     getAliases: function(doc) { return [doc.id]; }
   });

docs/config/processors/index-page.js

@@ -35,17 +35,7 @@ module.exports = function generateIndexPagesProcessor() {
 
         indexDoc.id = 'index' + (deployment.name === 'default' ? '' : '-' + deployment.name);
 
-        var deploymentDoc = {
-          docType: 'deploymentData',
-          id: 'deployment-data-' + deployment.name,
-          template: 'angular-service.template.js',
-          ngModuleName: 'deployment',
-          serviceName: 'DEPLOYMENT',
-          serviceValue: deployment.name
-        };
-
         docs.push(indexDoc);
-        docs.push(deploymentDoc);
       });
     }
   };

docs/config/processors/versions-data.js

@@ -55,6 +55,9 @@ module.exports = function generateVersionDocProcessor(gitData) {
 
         if (missesCurrentVersion) versions.push(currentVersion.version);
 
+        // Get the stable release with the highest version
+        var highestStableRelease = versions.reverse().find(semverIsStable);
+
         versions = versions
             .filter(function(versionStr) {
               return blacklist.indexOf(versionStr) === -1;
@@ -82,7 +85,21 @@ module.exports = function generateVersionDocProcessor(gitData) {
         var latest = sortObject(latestMap, reverse(semver.compare))
             .map(function(version) { return makeOption(version, 'Latest'); });
 
-        return [makeOption({version: 'snapshot'}, 'Latest', 'master')]
+        // Generate master and stable snapshots
+        var snapshots = [
+          makeOption(
+            {version: 'snapshot'},
+            'Latest',
+            'master-snapshot'
+          ),
+          makeOption(
+            {version: 'snapshot-stable'},
+            'Latest',
+            createSnapshotStableLabel(highestStableRelease)
+          )
+        ];
+
+        return snapshots
             .concat(latest)
             .concat(versions);
       }
@@ -112,6 +129,18 @@ module.exports = function generateVersionDocProcessor(gitData) {
       function sortObject(obj, cmp) {
         return Object.keys(obj).map(function(key) { return obj[key]; }).sort(cmp);
       }
+
+      // https://github.com/kaelzhang/node-semver-stable/blob/34dd29842409295d49889d45871bec55a992b7f6/index.js#L25
+      function semverIsStable(version) {
+        var semverObj = semver.parse(version);
+        return semverObj === null ? false : !semverObj.prerelease.length;
+      }
+
+      function createSnapshotStableLabel(version) {
+        var label = 'v' + version.replace(/.$/, 'x') + '-snapshot';
+
+        return label;
+      }
     }
   };
 };

docs/config/services/deployments/debug.js

@@ -26,7 +26,6 @@ module.exports = function debugDeployment(getVersion) {
       'js/all-versions-data.js',
       'js/pages-data.js',
       'js/nav-data.js',
-      'js/deployment-data-debug.js',
       'js/docs.js'
     ],
     stylesheets: [

docs/config/services/deployments/default.js

@@ -26,7 +26,6 @@ module.exports = function defaultDeployment(getVersion) {
       'js/all-versions-data.js',
       'js/pages-data.js',
       'js/nav-data.js',
-      'js/deployment-data-default.js',
       'js/docs.min.js'
     ],
     stylesheets: [

docs/config/services/deployments/jquery.js

@@ -30,7 +30,6 @@ module.exports = function jqueryDeployment(getVersion) {
       'js/all-versions-data.js',
       'js/pages-data.js',
       'js/nav-data.js',
-      'js/deployment-data-jquery.js',
       'js/docs.min.js'
     ],
     stylesheets: [

docs/config/services/deployments/production.js

@@ -7,24 +7,25 @@ var angularCodeUrl = '//code.angularjs.org/';
 
 var cdnUrl = googleCdnUrl + versionInfo.cdnVersion;
 
-// The plnkr examples must use the code.angularjs.org repo for the snapshot,
-// and the cdn for the tagged version and, if the build is not tagged, the currentVersion.
-//
-// The currentVersion may not be available on the cdn (e.g. if built locally, or hasn't been pushed
-// yet). This will lead to a 404, but this is preferable to loading a version with which the example
-// might not work (possibly in subtle ways).
-var examplesCdnUrl = versionInfo.currentVersion.isSnapshot ?
-  (angularCodeUrl + 'snapshot') :
-  (googleCdnUrl + (versionInfo.currentVersion.version || versionInfo.currentVersion));
+// The "examplesDependencyPath" here applies to the examples when they are opened in plnkr.co.
+// The embedded examples instead always include the files from the *default* deployment,
+// to ensure that the source files are always available.
+// The plnkr examples must always use the code.angularjs.org source files.
+// We cannot rely on the CDN files here, because they are not deployed by the time
+// docs.angularjs.org and code.angularjs.org need them.
+var versionPath = versionInfo.currentVersion.isSnapshot ?
+  'snapshot' :
+  (versionInfo.currentVersion.version || versionInfo.currentVersion.version);
+var examplesDependencyPath = angularCodeUrl + versionPath + '/';
 
 module.exports = function productionDeployment(getVersion) {
   return {
     name: 'production',
     examples: {
       commonFiles: {
-        scripts: [examplesCdnUrl + '/angular.min.js']
+        scripts: [examplesDependencyPath + 'angular.min.js']
       },
-      dependencyPath: examplesCdnUrl + '/'
+      dependencyPath: examplesDependencyPath
     },
     scripts: [
       cdnUrl + '/angular.min.js',
@@ -43,7 +44,6 @@ module.exports = function productionDeployment(getVersion) {
       'https://code.angularjs.org/snapshot/docs/js/all-versions-data.js',
       'js/pages-data.js',
       'js/nav-data.js',
-      'js/deployment-data-production.js',
       'js/docs.min.js'
     ],
     stylesheets: [

docs/config/templates/app/error.template.html

@@ -9,7 +9,7 @@
     <pre class="minerr-errmsg" error-display="{$ doc.formattedErrorMessage $}">{$ doc.formattedErrorMessage $}</pre>
 </div>
 
-<h2>Description</h2>
+<h2 id="description">Description</h2>
 <div class="description">
   {$ doc.description | marked $}
 </div>

docs/config/templates/app/indexPage.template.html

@@ -108,6 +108,7 @@
                   <li><a href="misc/contribute">Contribute</a></li>
                   <li><a href="https://github.com/angular/angular-seed">Seed App project template</a></li>
                   <li><a href="https://github.com/angular/angular.js">GitHub</a></li>
+                  <li><a href="https://github.com/angular/angular.js/blob/master/CHANGELOG.md">Changelog</a></li>
                   <li><a href="http://code.angularjs.org/">Download</a></li>
                 </ul>
               </li>
@@ -132,7 +133,7 @@
                 <div ng-repeat="(key, value) in results track by key" class="search-results-group" ng-class="colClassName + ' col-group-' + key" ng-show="value.length > 0">
                   <h4 class="search-results-group-heading">{{ key }}</h4>
                   <ul class="search-results">
-                    <li ng-repeat="item in value" class="search-result"><a ng-click="hideResults()" ng-href="{{ item.path }}">{{ item.name }}</a></li>
+                    <li ng-repeat="item in value" class="search-result"><a ng-click="handleResultClicked($event)" ng-href="{{ item.path }}">{{ item.name }}</a></li>
                   </ul>
                 </div>
               </div>
@@ -198,7 +199,7 @@
         </div>
         <div class="grid-right">
           <div id="loading" ng-show="loading">Loading...</div>
-          <div ng-hide="loading" ng-include="partialPath" autoscroll></div>
+          <div ng-hide="loading" ng-include="partialPath" toc-collector autoscroll></div>
         </div>
       </div>
     </section>

docs/config/templates/examples/runnableExample.template.html

@@ -18,7 +18,7 @@
     </div>
   {% endfor %}
 
-    <iframe class="runnable-example-frame" ng-src="{{getExampleIndex('{$ doc.example.deployments.default.path $}')}}" name="{$ doc.example.id $}"></iframe>
+    <iframe class="runnable-example-frame" src="{$ doc.example.deployments.default.outputPath $}" name="{$ doc.example.id $}"></iframe>
   </div>
 </div>
 

docs/config/templates/ngdoc/api/api.template.html

@@ -23,6 +23,7 @@
 
 {% block description %}
 <div class="api-profile-description">
+  <h2 id="overview">Overview</h2>
   {$ doc.description | marked $}
 </div>
 {% endblock %}
@@ -51,7 +52,7 @@
 
   {% block examples %}
   {%- if doc.examples %}
-  <h2 id="example">Examples</h2>
+  <h2 id="examples">{$ "Examples" if doc.examples | length > 1 else "Example" $}</h2>
   {%- for example in doc.examples -%}
     {$ example | marked $}
   {%- endfor -%}

docs/config/templates/ngdoc/api/directive.template.html

@@ -2,7 +2,7 @@
 {% extends "api/api.template.html" %}
 
 {% block additional %}
-  <h2>Directive Info</h2>
+  <h2 id="{$ doc.name $}-info">Directive Info</h2>
   <ul>
     {% if doc.scope %}<li>This directive creates new scope.</li>{% endif %}
     <li>This directive executes at priority level {$ doc.priority $}.</li>
@@ -29,10 +29,23 @@
       </li>
     {% endif -%}
 
+
+    {% set hasNameAsParam = false %}
+
+    {# when a directive's name is not a parameter (i.e. doesn't take a value),
+      add the directive name to the list of attributes and/or css classes #}
+
+    {%- for param in doc.params %}
+    {% set hasNameAsParam = true if param.name === doc.name else hasNameAsParam %}
+    {%- endfor %}
+
     {%- if doc.restrict.attribute -%}
       <li>as attribute:
         {% code %}
         <{$ doc.element $}
+          {%- if not hasNameAsParam %}
+          {$ lib.directiveParam(doc.name, {}, '', '') $}
+          {%- endif -%}
           {%- for param in doc.params %}
           {$ lib.directiveParam(param.name, param.type, '="', '"') $}
           {%- endfor %}>
@@ -43,10 +56,14 @@
     {% endif -%}
 
     {%- if doc.restrict.cssClass -%}
+
       <li>as CSS class:
         {% code %}
         {% set sep = joiner(' ') %}
         <{$ doc.element $} class="
+        {%- if not hasNameAsParam -%}
+          {$ sep() $}{$ lib.directiveParam(doc.name, {}, '', '') $}
+        {%- endif -%}
         {%- for param in doc.params -%}
           {$ sep() $}{$ lib.directiveParam(param.name, param.type, ': ', ';') $}
         {%- endfor %}"> ... </{$ doc.element $}>

docs/config/templates/ngdoc/api/filter.template.html

@@ -2,7 +2,7 @@
 {% extends "api/api.template.html" %}
 
 {% block additional %}
-  <h2>Usage</h2>
+  <h2 id="usage">Usage</h2>
   <h3>In HTML Template Binding</h3>
   {% if doc.usage %}
     {$ doc.usage | code $}

docs/config/templates/ngdoc/api/module.template.html

@@ -8,7 +8,7 @@
 
 {$ x.deprecatedBlock(doc) $}
 
-<h2>Installation</h2>
+<h2 id="module-installation">Installation</h2>
 {% if doc.installation or doc.installation == '' %}
   {$ doc.installation | marked $}
 {% else %}
@@ -76,7 +76,7 @@
 
 {% if doc.componentGroups.length %}
 <div class="component-breakdown">
-  <h2>Module Components</h2>
+  <h2 id="module-components">Module Components</h2>
   {% for componentGroup in doc.componentGroups %}
   <div>
     <h3 class="component-heading" id="{$ componentGroup.groupType | dashCase $}">{$ componentGroup.groupType | title $}</h3>
@@ -98,7 +98,7 @@
 {% endif %}
 
 {% if doc.usage %}
-  <h2>Usage</h2>
+  <h2 id="module-usage">Usage</h2>
   {$ doc.usage | marked $}
 {% endif %}
 

docs/config/templates/ngdoc/lib/events.template.html

@@ -2,11 +2,11 @@
 {% import "lib/deprecated.html" as x -%}
 
 {%- if doc.events %}
-<h2>Events</h2>
+<h2 id="events">Events</h2>
 <ul class="events">
   {%- for event in doc.events %}
   <li id="{$ event.name $}">
-    <h3>{$ event.name $}</h3>
+    <h3 id="event-{$ event.name $}">{$ event.name $}</h3>
     <div>{$ event.description | marked $}</div>
 
     {$ x.deprecatedBlock(event) $}
@@ -27,7 +27,7 @@
     {% endif -%}
     {%- if event.params %}
     <section class="api-section">
-      <h3>Parameters</h3>
+      <h4>Parameters</h4>
       {$ lib.paramTable(event.params) $}
     </section>
     {%- endif -%}

docs/config/templates/ngdoc/lib/methods.template.html

@@ -2,11 +2,11 @@
 {% import "lib/deprecated.html" as x -%}
 
 {%- if doc.methods %}
-<h2>Methods</h2>
+<h2 id="{$ doc.name $}-methods">Methods</h2>
 <ul class="methods">
   {%- for method in doc.methods %}
-  <li id="{$ method.name $}">
-    <h3>{$ lib.functionSyntax(method) $}</h3>
+  <li>
+    <h3 id="{$ method.name $}">{$ lib.functionSyntax(method) $}</h3>
     <div>{$ method.description | marked $}</div>
 
     {$ x.deprecatedBlock(method) $}
@@ -27,7 +27,7 @@
     {% endif %}
 
     {%- if method.examples %}
-    <h4 id="{$ doc.name $}.{$ method.name $}-examples">Examples</h4>
+    <h4 id="{$ doc.name $}.{$ method.name $}-examples">{$ "Examples" if method.examples | length > 1 else "Example" $}</h4>
     {%- for example in method.examples -%}
       {$ example | marked $}
     {%- endfor -%}

docs/config/templates/ngdoc/lib/params.template.html

@@ -1,7 +1,7 @@
 {% import "lib/macros.html" as lib -%}
 {%- if doc.params %}
 <section class="api-section">
-  <h3>Arguments</h3>
+  <h3 id="{$ doc.name $}-arguments">Arguments</h3>
 {$ lib.paramTable(doc.params) $}
 </section>
 {%- endif -%}

docs/config/templates/ngdoc/lib/properties.template.html

@@ -2,11 +2,11 @@
 {% import "lib/deprecated.html" as x -%}
 
 {%- if doc.properties %}
-<h2>Properties</h2>
+<h2 id="{$ doc.name $}-properties">Properties</h2>
 <ul class="properties">
   {%- for property in doc.properties %}
-  <li id="{$ property.name $}">
-    <h3>{$ property.name | code $}</h3>
+  <li>
+    <h3 id="{$ property.name $}">{$ property.name | code $}</h3>
     {$ lib.typeInfo(property) $}
     {$ x.deprecatedBlock(property) $}
   </li>

docs/config/templates/ngdoc/lib/returns.template.html

@@ -1,5 +1,5 @@
 {% import "lib/macros.html" as lib -%}
 {% if doc.returns -%}
-<h3>Returns</h3>
+<h3 id="{$ doc.name $}-returns">Returns</h3>
 {$ lib.typeInfo(doc.returns) $}
 {%- endif %}

docs/content/guide/animations.ngdoc

@@ -232,8 +232,8 @@ triggered:
 | {@link ng.directive:ngClass#animations ngClassEven / ngClassOdd}              | add and remove                                                            |
 | {@link ng.directive:ngHide#animations ngHide}                                 | add and remove (the `ng-hide` class)                                      |
 | {@link ng.directive:ngShow#animations ngShow}                                 | add and remove (the `ng-hide` class)                                      |
-| {@link ng.directive:ngModel#animation-hooks ngModel}                          | add and remove ({@link ng.directive:ngModel#css-classes various classes}) |
-| {@link ng.directive:form#animation-hooks form / ngForm}                       | add and remove ({@link ng.directive:form#css-classes various classes})    |
+| {@link ng.directive:ngModel#animations ngModel}                          | add and remove ({@link ng.directive:ngModel#css-classes various classes}) |
+| {@link ng.directive:form#animations form / ngForm}                       | add and remove ({@link ng.directive:form#css-classes various classes})    |
 | {@link module:ngMessages#animations ngMessages}                               | add and remove (the `ng-active`/`ng-inactive` classes)                    |
 
 For a full breakdown of the steps involved during each animation event, refer to the

docs/content/guide/bootstrap.ngdoc

@@ -144,7 +144,7 @@ This is the sequence that your code should follow:
 
 ## Things to keep in mind
 
-There a few things to keep in mind regardless of automatic or manual bootstrapping:
+There are a few things to keep in mind regardless of automatic or manual bootstrapping:
 
 - While it's possible to bootstrap more than one AngularJS application per page, we don't actively
   test against this scenario. It's possible that you'll run into problems, especially with complex apps, so

docs/content/guide/directive.ngdoc

@@ -977,7 +977,7 @@ controllers using `require`.
 Otherwise use `link`.
 </div>
 
-### Summary
+## Summary
 
 Here we've seen the main use cases for directives. Each of these samples acts as a good starting
 point for creating your own directives.

docs/content/guide/e2e-testing.ngdoc

@@ -8,7 +8,7 @@
 <div class="alert alert-danger">
 **Note:** In the past, end-to-end testing could be done with a deprecated tool called
 [Angular Scenario Runner](http://code.angularjs.org/1.2.16/docs/guide/e2e-testing). That tool
-is now in maintenance mode.
+is now in maintenance mode, and will be removed in version 1.7.0.
 </div>
 
 As applications grow in size and complexity, it becomes unrealistic to rely on manual testing to

docs/content/guide/expression.ngdoc

@@ -37,7 +37,8 @@ Angular expressions are like JavaScript expressions with the following differenc
     even inside `ng-init` directive.
 
   * **No RegExp Creation With Literal Notation:** You cannot create regular expressions
-    in an Angular expression.
+    in an AngularJS expression. An exception to this rule is {@link ngPattern `ng-pattern`} which accepts valid
+    RegExp.
 
   * **No Object Creation With New Operator:** You cannot use `new` operator in an Angular expression.
 

docs/content/guide/migration.ngdoc

@@ -15,22 +15,6 @@ which drives many of these changes.
 * Several new features, especially animations, would not be possible without a few changes.
 * Finally, some outstanding bugs were best fixed by changing an existing API.
 
-
-
-## Contents
-
-<ul class="nav nav-list">
-  <li>{@link guide/migration#migrating-from-1-5-to-1-6 Migrating from 1.5 to 1.6}</li>
-  <li>{@link guide/migration#migrating-from-1-4-to-1-5 Migrating from 1.4 to 1.5}</li>
-  <li>{@link guide/migration#migrating-from-1-3-to-1-4 Migrating from 1.3 to 1.4}</li>
-  <li>{@link guide/migration#migrating-from-1-2-to-1-3 Migrating from 1.2 to 1.3}</li>
-  <li>{@link guide/migration#migrating-from-1-0-to-1-2 Migrating from 1.0 to 1.2}</li>
-</ul>
-
-
-
-
-
 ## Migrating from 1.5 to 1.6
 
 Angular 1.6 fixes numerous bugs and adds new features, both in core and in external modules.
@@ -1405,7 +1389,7 @@ always assumed to be of type 'string', so passing non-string values never worked
 The main difference is that now it will fail faster and with a more informative error message.
 
 
-## ngTouch (`ngClick`)
+### ngTouch (`ngClick`)
 
 Due to [0dfc1dfe](https://github.com/angular/angular.js/commit/0dfc1dfebf26af7f951f301c4e3848ac46f05d7f),
 the `ngClick` override directive from the `ngTouch` module is **deprecated and disabled by default**.
@@ -1566,7 +1550,7 @@ class based animations (animations triggered via ngClass) in order to ensure tha
 
 
 
-### Forms (`ngMessages`, `ngOptions`, `select`, `ngPattern` and `pattern`)
+### Forms (`ngMessages`, `ngOptions`, `select`, `ngPattern` and `pattern`, `form`)
 
 #### ngMessages
 The ngMessages module has also been subject to an internal refactor to allow it to be more flexible
@@ -1748,7 +1732,7 @@ the built-in pattern validator:
 ```
 
 
-### form
+#### form
 
 Due to [94533e57](https://github.com/angular/angular.js/commit/94533e570673e6b2eb92073955541fa289aabe02),
 the `name` attribute of `form` elements can now only contain characters that can be evaluated as part

docs/content/guide/production.ngdoc

@@ -20,6 +20,9 @@ and adds CSS classes to data-bound elements:
 CSS class are attached to the corresponding element. These scope references can then be accessed via
 `element.scope()` and `element.isolateScope()`.
 
+- Placeholder comments for structural directives will contain information about what directive
+and binding caused the placeholder. E.g. `<!-- ngIf: shouldShow() -->`.
+
 Tools like [Protractor](https://github.com/angular/protractor) and
 [Batarang](https://github.com/angular/angularjs-batarang) need this information to run,
 but you can disable this in production for a significant performance boost with:

docs/content/misc/contribute.ngdoc

@@ -2,185 +2,12 @@
 @name Develop
 @description
 
-# Building and Testing AngularJS
+# Contributing & Development
 
-This document describes how to set up your development environment to build and test AngularJS, and
-explains the basic mechanics of using `git`, `node`, `yarn`, `grunt`, and `bower`.
-
-See the [contributing guidelines](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md)
-for how to contribute your own code to AngularJS.
-
-
-1. {@link misc/contribute#installing-dependencies Installing Dependencies}
-2. {@link misc/contribute#forking-angular-on-github Forking Angular on Github}
-3. {@link misc/contribute#building-angularjs Building AngularJS}
-4. {@link misc/contribute#running-a-local-development-web-server Running a Local Development Web Server}
-5. {@link misc/contribute#running-the-unit-test-suite Running the Unit Test Suite}
-6. {@link misc/contribute#running-the-end-to-end-test-suite Running the End-to-end Test Suite}
-
-## Installing Dependencies
-
-Before you can build AngularJS, you must install and configure the following dependencies on your
-machine:
-
-* [Git](http://git-scm.com/): The [Github Guide to
-  Installing Git](https://help.github.com/articles/set-up-git) is a good source of information.
-
-* [Node.js v6.x (LTS)](http://nodejs.org): We use Node to generate the documentation, run a
-  development web server, run tests, and generate distributable files. Depending on your system,
-  you can install Node either from source or as a pre-packaged bundle.
-
-  We recommend using [nvm](https://github.com/creationix/nvm) (or [nvm-windows](https://github.com/coreybutler/nvm-windows))
-  to manage and install Node.js, which makes it easy to change the version of Node.js per project.
-
-* [Yarn](https://yarnpkg.com): We use Yarn to install our Node.js module dependencies (rather than using npm).
-  There are detailed installation instructions available at https://yarnpkg.com/en/docs/install.
-
-* [Java](http://www.java.com): We minify JavaScript using our
-  [Closure Tools](https://developers.google.com/closure/) jar. Make sure you have Java (version 7 or higher)
-  installed and included in your [PATH](http://docs.oracle.com/javase/tutorial/essential/environment/paths.html)
-  variable.
-
-* [Grunt](http://gruntjs.com): We use Grunt as our build system. Install the grunt command-line tool globally with:
-
-  ```shell
-  yarn global add grunt-cli
-  ```
-
-## Forking Angular on Github
-
-To create a Github account, follow the instructions [here](https://github.com/signup/free).
-Afterwards, go ahead and [fork](http://help.github.com/forking) the [main AngularJS repository](https://github.com/angular/angular.js).
-
-
-## Building AngularJS
-
-To build AngularJS, you clone the source code repository and use Grunt to generate the non-minified and
-minified AngularJS files:
-
-```shell
-# Clone your Github repository:
-git clone https://github.com/<github username>/angular.js.git
-
-# Go to the AngularJS directory:
-cd angular.js
-
-# Add the main AngularJS repository as an upstream remote to your repository:
-git remote add upstream "https://github.com/angular/angular.js.git"
-
-# Install node.js dependencies:
-yarn install
-
-# Build AngularJS (which will install `bower` dependencies automatically):
-grunt package
-```
-
-
-<div class="alert alert-warning">
-**Note:** If you're using Windows, you must use an elevated command prompt (right click, run as
-Administrator). This is because `grunt package` creates some symbolic links.
-</div>
-
-<div class="alert alert-warning">
-**Note:** If you're using Linux, and `yarn install` fails with the message
-'Please try running this command again as root/Administrator.', you may need to globally install `grunt` and `bower`:
-<ul>
-<li>sudo yarn global add grunt-cli</li>
-<li>sudo yarn global add bower</li>
-</ul>
-
-</div>
-
-The build output can be located under the `build` directory. It consists of the following files and
-directories:
-
-* `angular-<version>.zip` — The complete zip file, containing all of the release build
-artifacts.
-
-* `angular.js` — The non-minified `angular` script.
-
-* `angular.min.js` —  The minified `angular` script.
-
-* `angular-scenario.js` — The `angular` End2End test runner.
-
-* `docs/` — A directory that contains all of the files needed to run `docs.angularjs.org`.
-
-* `docs/index.html` — The main page for the documentation.
-
-* `docs/docs-scenario.html` — The End2End test runner for the documentation application.
-
-
-## Running a Local Development Web Server
-
-To debug code and run end-to-end tests, it is often useful to have a local HTTP server. For this purpose, we have
-made available a local web server based on Node.js.
-
-1. To start the web server, run:
-   ```shell
-   grunt webserver
-   ```
-
-2. To access the local server, enter the following URL into your web browser:
-   ```text
-   http://localhost:8000/
-   ```
-   By default, it serves the contents of the AngularJS project directory.
-
-3. To access the locally served docs, visit this URL:
-   ```text
-   http://localhost:8000/build/docs/
-   ```
-
-## Running the Unit Test Suite
-
-We write unit and integration tests with Jasmine and execute them with Karma. To run all of the
-tests once on Chrome run:
-
-```shell
-grunt test:unit
-```
-
-To run the tests on other browsers (Chrome, ChromeCanary, Firefox and Safari are pre-configured) use:
-
-```shell
-grunt test:unit --browsers=Chrome,Firefox
-```
-
-Note there should be _no spaces between browsers_. `Chrome, Firefox` is INVALID.
-
-During development, however, it's more productive to continuously run unit tests every time the source or test files
-change. To execute tests in this mode run:
-
-1. To start the Karma server, capture Chrome browser and run unit tests, run:
-
-   ```shell
-   grunt autotest
-   ```
-
-2. To capture more browsers, open this URL in the desired browser (URL might be different if you have multiple instance
-   of Karma running, read Karma's console output for the correct URL):
-
-   ```text
-   http://localhost:9876/
-   ```
-
-3. To re-run tests just change any source or test file.
-
-
-To learn more about all of the preconfigured Grunt tasks run:
-
-```shell
-grunt --help
-```
-
-
-## Running the End-to-end Test Suite
-
-Angular's end to end tests are run with Protractor. Simply run:
-
-```shell
-grunt test:e2e
-```
-
-This will start the webserver and run the tests on Chrome.
+For everything related to contributing, we have a document in our Git Repository that covers the
+basics about support channels, creating issues, and pull requests:
+[Contributing](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md).
 
+For developers, we have a more detailed document that covers project setup, coding rules, and
+a guide to writing documentation:
+[Developing](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md).

docs/content/misc/started.ngdoc

@@ -16,9 +16,9 @@ becoming an Angular expert.
    starter app with a directory layout, test harness, and scripts to begin building your application.
 
 
-# Further Steps
+## Further Steps
 
-## Watch Videos
+### Watch Videos
 
 If you haven’t had a chance to watch the videos from the homepage, please check out:
 
@@ -29,13 +29,13 @@ If you haven’t had a chance to watch the videos from the homepage, please chec
 And visit our [YouTube channel](http://www.youtube.com/user/angularjs) for more AngularJS video presentations and
 tutorials.
 
-## Subscribe
+### Subscribe
 
 * Subscribe to the [mailing list](http://groups.google.com/forum/?fromgroups#!forum/angular).  Ask questions here!
 * Follow us on [Twitter](https://twitter.com/intent/follow?original_referer=http%3A%2F%2Fangularjs.org%2F&region=follow_link&screen_name=angular&source=followbutton&variant=2.0)
 * Add us to your circles on [Google+](https://plus.google.com/110323587230527980117/posts)
 
-## Read more
+### Read more
 
 The AngularJS documentation includes the {@link guide/index Developer Guide} covering concepts and the
 {@link ./api API Reference} for syntax and usage.

docs/content/tutorial/step_14.ngdoc

@@ -328,7 +328,7 @@ The applied CSS classes are much the same as with `ngRepeat`. Each time a new pa
 ensures that all views are contained within a single HTML element, which allows for easy animation
 control.
 
-For more on CSS animations, see the [Web Platform documentation][webplatform-animations].
+For more on CSS animations, see the [MDN web docs][mdn-animations].
 
 
 ## Animating `ngClass` with JavaScript
@@ -561,4 +561,4 @@ There you have it! We have created a web application in a relatively short amoun
 [caniuse-css-transitions]: http://caniuse.com/#feat=css-transitions
 [jquery]: https://jquery.com/
 [jquery-animate]: https://api.jquery.com/animate/
-[webplatform-animations]: https://docs.webplatform.org/wiki/css/properties/animations
+[mdn-animations]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations

firebase.json

@@ -1,6 +1,6 @@
 {
   "hosting": {
-    "public": "build/docs",
+    "public": "uploadDocs",
     "ignore": [
       "/index.html",
       "/index-debug.html",
@@ -16,7 +16,7 @@
         "destination": "/index-production.html"
       },
       {
-        "source": "**/*!(.jpg|.jpeg|.gif|.png|.html|.js|.json|.css|.svg|.ttf|.woff|.woff2|.eot)",
+        "source": "**/*!(.jpg|.jpeg|.gif|.png|.html|.js|.map|.json|.css|.svg|.ttf|.woff|.woff2|.eot)",
         "destination": "/index-production.html"
       }
     ]