update README with development workflow

1 files changed, 148 insertions, 8 deletions

diff --git a/README.md b/README.md
index 54fb6fef7ef..75ec966a214 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,151 @@
-# Code
+# Visual Studio Code
 
-Code is a new choice in developer tools, one that combines the
-the simplicity and streamlined experience of a code editor with
-the best of what developers need for their core edit-compile-debug cycle.
+VS Code is a new choice of tool that combines the simplicity of a
+code editor with what developers need for their core
+edit-build-debug cycle. It is the first editor and first cross platform
+tool in the Visual Studio family of products.
 
-Code is the heart of [Visual Studio Code](http://code.visualstudio.com),
-the first code editor and first cross-platform development tool in the
-Visual Studio family.
+Code incorporates Visual Studio's world class editing and debugging experiences
+whlie integrating with existing tools. A rich extensibility model and
+ecosystem provides support for a broad array of languages and tools that
+integrate seamlessly with Code.
+
+The VSCode repository is where the Code team does development. We
+encourage you to follow along, take part in the discussion, submit
+issues, suggest a feature, or create a pull request!
+
+Follow us [@code](https://twitter.com/code).
+
+## Installation and Documentation
+Download the latest build for your platform from the
+[Visual Studio Code](http://code.visualstudio.com) website. Once
+installed, Code will automatically update itself when we publish
+new releases.
+
+Everything you need to know about using and extending Code can be
+found in our online [documentation](http://code.visualstudio.com/docs).
+Found a typo? Want to clarify something? Clone the
+[vscode-docs](https://github.com/microsoft/vscode-docs) repository
+and make a pull request.
+
+## Contributing
+
+There are many ways to contribute to the Code project. For example:
+
+* [Submit bugs](https://github.com/microsoft/vscode/issues) and help
+us verify fixes as they are checked in
+* Review [source code changes](https://github.com/microsoft/vscode/pulls)
+* Engage with users and other developers on [Stack Overflow](http://go.microsoft.com/fwlink/?LinkID=536384)
+* [Fix a bug and make a pull request](https://github.com/Microsoft/vscode/wiki/How-to-Contribute)
+* Review the [documentation](https://github.com/microsoft/vscode-docs)
+and make pull requests for anything from typos to new content
+
+Check out [How to Contribute](https://github.com/Microsoft/vscode/wiki) for more information.
+
+## Build and Run From Source
+
+If you want to understand how Code works or want to debug an issue, you'll want to get the source,
+build it, and run the tool locally.
+
+### Installing Prerequisites
+
+[Download the latest version](https://code.visualstudio.com/Download) of Visual Studio Code (you will use Code to edit Code!)
+
+VS Code includes node module dependencies that require native compilation. To ensure the compilation is picking up the right version of
+header files from the Electron Shell, we have our own script to run the installation via npm (`scripts/npm`).
+
+**Tip!** In case you fail to build the native modules you can copy the node_modules folder of the VS Code installation
+into the VSCode workspaces node_modules folder. You will still need to run `scripts/npm install` to get all the development dependencies installed.
+
+For native compilation, you will need python (version `v2.7` recommended, `v3.x.x` is __*not*__ supported) as well as a C/C++ compiler tool chain.
+
+**Windows:**
+* In addition to Python v2.7, make sure you have a PYTHON environment variable set to `drive:\path\to\python.exe`, not to a folder
+* Visual Studio 2013 for Windows Desktop or [Visual Studio 2015](https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx)
+, make sure to select the option to install all C++ tools and the Windows SDK
+
+**OS X** Command line developer tools
+* Python should be installed already
+* [XCode](https://developer.apple.com/xcode/downloads/) and the Command Line Tools (XCode -> Preferences -> Downloads), which will
+install `gcc` and the related toolchain containing `make`
+
+**Linux:**
+* Python v2.7
+* `make`
+* A proper C/C++ compiler toolchain, for example [GCC](https://gcc.gnu.org)
+
+After you have these tools installed, run the following commands to check out Code and install it:
+
+OS X
+
+	git clone https://github.com/microsoft/vscode
+	cd vscode && npm install -g mocha gulp
+	./scripts/npm.sh install
+
+Windows
+
+	git clone https://github.com/microsoft/vscode
+	cd vscode
+	npm install -g mocha gulp
+	scripts\npm install
+
+Linux
+
+	git clone https://github.com/microsoft/vscode
+	cd vscode && npm install -g mocha gulp
+	# for 32bit, pass --arch=ia32
+	./scripts/npm.sh install --arch=x64
+
+## Development Workflow
+
+### Incremental Build
+Open VS Code on the folder where you have cloned the vscode repository and press
+`CTRL+SHIFT+B` on Windows or `COMMAND+SHIFT+B` on OSX to start the TypeScript
+builder. It will do an initial full build and then watch for file changes, compiling
+those changes *incrementally*. To view the build output open the Output stream by pressing `Shift+CMD+U`.
+
+### Errors and Warnigns
+Errors and warnings are indicated in the status bar at the bottom left. You can
+view the error list using `View | Errors and Warnings` or pressing `CMD+P` and then `!`.
+Please note, if you start the TypeScript builder from a terminal using `gulp watch`, errors
+and warnings will only show in the console and not in Code.
+
+**Tip!** You do not need to stop and restart the development version after each change,
+you can just execute `Reload Window` from the command palette.
+
+### Running Tests
+To test the changes you launch a development version of VS Code on the workspace
+`vscode`, which youare currently editing.
+
+
+OS X and Linux
+
+	./scripts/code.sh
+
+Windows
+
+	.\scripts\code.bat
+
+You can identify the development version of Code by the Electron icon in the Dock or Taskbar.
+
+### Debugging
+VS Code uses a multi process architecture and your code is executed in different
+processes:
+* the render process runs the UI code inside the Shell window
+* the plugin host process runs code implemented by a plugin
+
+To debug code that runs in the renderer process you launch the Chrome Developers Tools using
+`Help | Toggle Developer Tools`.
+
+To debug code that runs inside the plugin host process you open another instance of the Chrome
+Developer Tools using `Developer: Reveal Plugin Host Process` from the command palette.
+
+**Tip!** When you are done debugging, use the 'Hide Window' button to close the Chrome Developer
+Tools on the Plugin Host Process, or use the command `Developer: Hide Plugin Host Process Window`.
+Do not close the window using the close button as this will also kill the plugin host process itself.
+
+### Unit Testing
+Press `SHIFT+CMD+T` (`CTRL+SHIFT+T` on Windows) to start the unit tests or run the tests directly
+from a terminal using `gulp test`. The [test README.md](test/README.md) has complete details on
+how to run tests and coverage reports.
 
-Follow us on twitter [@code](https://twitter.com/code)!