From 59b488383e0f2156458cbea19f3a6183cd0366d1 Mon Sep 17 00:00:00 2001
From: Stuart Rowlands <stuart.rowlands@acquia.com>
Date: Fri, 21 Oct 2016 11:36:58 +1000
Subject: [PATCH] Improvements to the Ubuntu Bash on Windows documentation.

---
 readme/windows-install.md | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/readme/windows-install.md b/readme/windows-install.md
index 191ab16ec..c3ce5c457 100644
--- a/readme/windows-install.md
+++ b/readme/windows-install.md
@@ -2,6 +2,8 @@
 
 BLT is supported on Windows 10, under the Windows Subsystem for Linux (Ubuntu Bash). You need to install this separately, and you must be running Windows 10 Anniversary edition or later, and the Windows installation must be 64-bit.
 
+There are a few [known issues and quirks](#known-issues-and-quirks) with this approach.
+
 ## Install the Windows Subsystem for Linux
 
 The Windows Subsystem for Linux allows you to use a full Linux environment via Bash on Ubuntu. This means you can install BLT's prerequisites on your Windows workstation in a similar way as you would on a Linux or Mac environment.
@@ -12,11 +14,12 @@ Follow Microsoft's official instructions to install [Bash on Ubuntu on Windows](
 
   1. `sudo add-apt-repository ppa:ondrej/php` (hit 'Enter' when prompted)
   2. `sudo apt-get update`
-  3. `sudo apt-get install -y php5.6-cli php5.6-curl php5.6-xml php5.6-mbstring php5.6-gd`
-  4. `sudo apt-get install -y git nodejs npm unzip`
+  3. `sudo apt-get install -y php5.6-cli php5.6-curl php5.6-xml php5.6-mbstring php5.6-bz2 php5.6-gd php5.6-mysql mysql-client unzip git`
   4. `php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"`
   5. `php composer-setup.php`
   6. `sudo mv composer.phar /usr/local/bin/composer`
+  7. `curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash -`
+  8. `sudo apt-get install -y nodejs`
 
 ## Other Required setup
 
@@ -47,3 +50,13 @@ After you run `vm init` (it may error out and say 'Virtualbox is missing is not
   - `wrun vagrant up` to start the VM
   - `wrun vagrant halt` to stop the VM
   - `wrun vagrant destroy -f` to delete the VM
+
+## Known issues and quirks
+
+As the WSL is a beta feature it is expected that some features may contain bugs or be incomplete.
+
+At the time of writing these are the currently known issues which you may encounter.
+
+  1. [Only portions of procfs are implemented, and there is limited inotify support](https://github.com/Microsoft/BashOnWindows/issues/216). This will impact things like Gulp where you commonly want to actively 'watch' for filesystem changes. In that particular instance you can use [gulp-watch](https://www.npmjs.com/package/gulp-watch) which polls periodically instead.
+  2. [Network enumeration is not supported](https://github.com/Microsoft/BashOnWindows/issues/468). This will impact networking functions commonly required by popular frontend packages and utilities (e.g Browsersync). There are workarounds discussed in the GitHub issue.
+  3. [Permissions on /dev/tty are sometimes incorrect](https://github.com/Microsoft/BashOnWindows/issues/617). This can prevent ssh connectivity keyboard input cannot be read (required when entering a passphrase). A workaround is discussed in the GitHub issue.