From fc881390d03eaccdc13aba64e1fc86707bfe009b Mon Sep 17 00:00:00 2001
From: Keen Yee Liau <kyliau@google.com>
Date: Thu, 20 Dec 2018 16:32:22 -0800
Subject: [PATCH] docs(bazel): Getting started with Bazel + CLI (#27784)

PR Close #27784
---
 packages/bazel/src/schematics/README.md | 77 +++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/packages/bazel/src/schematics/README.md b/packages/bazel/src/schematics/README.md
index 741a6952f0..5c1f563253 100644
--- a/packages/bazel/src/schematics/README.md
+++ b/packages/bazel/src/schematics/README.md
@@ -1,5 +1,82 @@
 # Schematics for Bazel
 
+## WARNING
+
+Schematics in `@angular/bazel` is still highly experimental as of January 2019,
+please use with caution. For feedbacks and comments, please open an issue on
+GitHub and ping [@mgechev](https://github.com/mgechev) or
+[@kyliau](https://github.com/kyliau).
+
+## Create a Bazel-managed Angular project
+
+To create a new Angular project that builds with Bazel, all you need to do is install the `@angular/bazel` package.
+
+The example below assumes that you have a global installation of Angular CLI.
+If not, please run `yarn global add @angular/cli`.
+
+Install the latest `@angular/bazel` for generating Bazel schematics.
+
+```
+$ yarn global add @angular/bazel
+```
+
+Create a new project using `@angular/bazel` schematics for `ng new`.
+
+```
+$ ng new demo --collection=@angular/bazel --defaults
+```
+
+In addition to the regular files generated by CLI, the following files that are
+specific to a Bazel workspace are also created.
+
+```
+...
+CREATE demo/BUILD.bazel (190 bytes)
+CREATE demo/WORKSPACE (2951 bytes)
+CREATE demo/.bazelignore (18 bytes)
+CREATE demo/.bazelrc (828 bytes)
+CREATE demo/e2e/BUILD.bazel (1230 bytes)
+CREATE demo/e2e/protractor.on-prepare.js (1101 bytes)
+CREATE demo/src/BUILD.bazel (2626 bytes)
+CREATE demo/src/initialize_testbed.ts (432 bytes)
+CREATE demo/src/main.dev.ts (185 bytes)
+CREATE demo/src/main.prod.ts (249 bytes)
+```
+
+Note that in a Bazel-managed project, there is a Bazel WORKSPACE file and a few BUILD.bazel files.
+There are also some files specific to a Bazel-managed project, namely `main.dev.ts` and `main.prod.ts`.
+This is because all Angular projects built with Bazel must be AOT only.
+In a Bazel project, `main.ts` generated by CLI is not used.
+
+By default, `ng new` for Bazel does not perform `yarn install`.
+This is because the `node_modules` are managed by Bazel and it is Bazel's
+responsibility to perform the install.
+
+Next, let's try to build the project using Bazel.
+All existing `ng` commands would work as before.
+
+```
+cd demo
+# The following yarn step is needed so that `ng build` works correctly.
+# Alternatively, you can skip this step if you choose to not use `ng` commands.
+# In which case, you'd execute `yarn bazel build //src:bundle`. This is
+# equivalent to running `ng build`.
+yarn
+ng build
+ng serve
+```
+
+If you encounter a warning about version mismatch, update `ANGULAR_VERSION` in
+the WORKSPACE file to match the version of `@angular/bazel` installed from NPM.
+
+Bring up the dev server using `ibazel run` command.
+
+```
+yarn ibazel run //src:devserver
+```
+
+Make some changes to the code, and verify that the dev server automatically refreshes.
+
 ## Development notes
 
 To test any local changes, run