Updated readme to match master layout

StephenHodgson · web-flow · commit a9c1183f6b19 · 2017-10-16T11:34:28.000-07:00
diff --git a/README.md b/README.md
@@ -1,13 +1,54 @@
-# MixedRealityToolkit Dev_Unity_2017.2.0 branch
-This is a development branch for Windows Mixed Reality immersive headset support.
+<img src="External/ReadMeImages/MRTK_Logo_Rev.png">
 
-**IMPORTANT** You will also need a recent [Windows Insider SDK Preview](https://www.microsoft.com/en-us/software-download/windowsinsiderpreviewSDK) installed, or you will not be able to build this branch. 
+# What is MixedRealityToolkit-Unity?
+The Mixed Reality Toolkit is a collection of scripts and components intended to accelerate development of applications targeting Microsoft HoloLens and Windows Mixed Reality headsets.
+The project is aimed at reducing barriers to entry to create mixed reality applications and contribute back to the community as we all grow.
+
+MixedRealityToolkit-Unity uses code from the base [MixedRealityToolkit](https://github.com/Microsoft/MixedRealityToolkit) and makes it easier to consume in [Unity](https://unity3d.com/).
+
+<img src="External/ReadMeImages/MixedRealityStack.png">
+
+Learn more about [mixed reality](https://developer.microsoft.com/en-us/windows/mixed-reality/mixed_reality).
+
+[github-rel]:                  https://github.com/Microsoft/MixedRealityToolkit-Unity/releases/latest
+[github-rel-badge]:            https://img.shields.io/github/tag/microsoft/MixedRealityToolkit-unity.svg?style=flat-square&label=latest%20master%20branch%20release&colorB=007ec6
+[![Github Release][github-rel-badge]][github-rel]
 
 [unity-download]:                 http://beta.unity3d.com/download/edcd66fb22ae/download.html
 [unity-version-badge]:            https://img.shields.io/badge/current%20unity%20editor%20version-2017.2.0f3%20MRTP-green.svg
 [![Github Release][unity-version-badge]][unity-download]
 
-## New Features!
+# Feature areas
+| ![Input](External/ReadMeImages/MRTK170802_Short_03.png) [Input](Assets/HoloToolkit/Input/README.md)                                               | ![Sharing](External/ReadMeImages/MRTK170802_Short_04.png) [Sharing](Assets/HoloToolkit/Sharing/README.md)   | ![Spatial Mapping](External/ReadMeImages/MRTK170802_Short_05.png) [Spatial Mapping](Assets/HoloToolkit/SpatialMapping/README.md)| 
+| :------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
+| Scripts that leverage inputs such as gaze, gesture, voice and motion controllers.                                                                 | Sharing library enables collaboration across multiple devices.                                              | Scripts that allow applications to bring the real world into the digital using HoloLens.                                        | 
+| ![Spatial Sound](External/ReadMeImages/MRTK170802_Short_09.png) [Spatial Sound](Assets/HoloToolkit/SpatialSound/README.md)                        | ![UX Controls](External/ReadMeImages/MRTK170802_Short_10.png) [UX Controls](Assets/HoloToolkit/UX/README.md)| ![Utilities](External/ReadMeImages/MRTK170802_Short_11.png) [Utilities](Assets/HoloToolkit/Utilities/README.md)                 | 
+| Scripts to help plug spatial audio into your application.                                                                                         | Building blocks for creating good UX in your application like common controls.                              | Common helpers and tools that you can leverage in your application.                                                             |
+| ![Spatial Understanding](External/ReadMeImages/MRTK170802_Short_06.png) [Spatial Understanding](Assets/HoloToolkit/SpatialUnderstanding/README.md)| ![Build](External/ReadMeImages/MRTK170802_Short_12.png) [Build](Assets/HoloToolkit/BuildAndDeploy/README.md)| ![Boundary](External/ReadMeImages/MRTK170802_Short_06.png) [Build](Assets/HoloToolkit/Boundary/README.md)                       |
+| Tailor experiences based on room semantics like couch, wall etc.                                                                                  | Build and deploy automation window for Unity Editor.                                                        | Scripts that help with rendering the floor and boundaries for Immersive Devices.
+
+# Required Software
+| ![Windows 10 Creators Update](External/ReadMeImages/MRTK170802_Short_17.png) [Windows 10 Creators Update](https://www.microsoft.com/software-download/windows10)| ![Unity](External/ReadMeImages/MRTK170802_Short_18.png) [Unity](https://unity3d.com/get-unity/download/archive)| ![Visual Studio 2017](External/ReadMeImages/MRTK170802_Short_19.png) [Visual Studio 2017](http://dev.windows.com/downloads)| ![Hololens Emulator(optional)](External/ReadMeImages/MRTK170802_Short_20.png) [Hololens Emulator(optional)](https://go.microsoft.com/fwlink/?linkid=852626)|
+| :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| To develop apps for mixed reality headsets, you need the Fall Creators Update.                                                                                  | The Unity engine is an easy way to get started building a mixed reality app.                                   | Visual Studio is used for code editing, deploying and building UWP app packages.                                           | Emulator allows you test your app without the device in a simulated environment.                                                                           |
+
+# Getting started with MRTK
+| ![Hololens Emulator(optional)](External/ReadMeImages/MRTK170802c_Short_22.png) Quick start                        | ![Hololens Emulator(optional)](External/ReadMeImages/MRTK170802c_Short_23.png) Contributing to this project |
+| :---------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
+| Please go over the [Getting started guide](GettingStarted.md) to learn more about getting off the ground quickly. | Please go over the [Contributing guidelines](CONTRIBUTING.md) to learn more about the process and thinking. |
+
+## New Features with Fall Creators Update!
+
+### Prerequisites:
+1. See [Development PC specs](https://developer.microsoft.com/en-us/windows/mixed-reality/install_the_tools#developing_for_immersive_headsets) for tips on developing for immersive headsets.
+2. [Holograms 100](https://developer.microsoft.com/en-us/windows/mixed-reality/holograms_100) has been updated with how to setup Windows Mixed Reality in your app.
+3. [How to navigate the Windows Mixed Reality home](https://developer.microsoft.com/en-us/windows/mixed-reality/navigating_the_windows_mixed_reality_home).
+4. Development PC needs to be on the Fall Creators Update (Build 1709)
+5. [Visual Studio 2017](https://www.visualstudio.com/downloads/).
+    1. Install the 10.0.16267.0 SDK via Visual Studio Installer.
+6. Unity 2017.2.0f3 MRTP with Mixed Reality API support. This build of Unity can be found [here](http://beta.unity3d.com/download/edcd66fb22ae/download.html).
+    1. Please read more about [Immersive headset details](https://developer.microsoft.com/en-us/windows/mixed-reality/immersive_headset_details).
+
 <img src="External/ReadMeImages/MotionControllerTest_Teleport.png" width="700px">
 
 If you're looking for **Controller models**:
@@ -43,39 +84,72 @@ If you're looking for **Boundary** tools:
 * See:
     * BoundaryManager.cs
     * MixedRealityCameraParent.prefab
-    
-**External\How To** docs folder is meant to help everyone with migrating forward or any simple doubts they might have about the process.
-Please feel free to grow all these sections. We can't wait to see your additions!
 
-## Prerequisites:
-1. See [Development PC specs](https://developer.microsoft.com/en-us/windows/mixed-reality/install_the_tools#developing_for_immersive_headsets) for tips on developing for immersive headsets.
-2. [Holograms 100](https://developer.microsoft.com/en-us/windows/mixed-reality/holograms_100) has been updated with how to setup Windows Mixed Reality in your app.
-3. [How to navigate the Windows Mixed Reality home](https://developer.microsoft.com/en-us/windows/mixed-reality/navigating_the_windows_mixed_reality_home).
-4. Development PC needs to be on a recent Windows Insider SDK and a Windows Insider build as below.
-    1. Launch Settings > Updates and Security > Windows Insider Program > Get Insider Preview builds 
-    2. Install the SDK found [here](https://www.microsoft.com/en-us/software-download/windowsinsiderpreviewSDK).
-5. Unity 2017.2.0f3 MRTP with Mixed Reality API support. This build of Unity can be found [here](http://beta.unity3d.com/download/edcd66fb22ae/download.html).
-    1. Please read more about [Immersive headset details](https://developer.microsoft.com/en-us/windows/mixed-reality/immersive_headset_details).
-6. [Visual Studio 2017](https://www.visualstudio.com/downloads/).
+# Roadmaps
+### Master branch
+| Target Unity release  | Release timeframe | Master release tag | Toolkit release features |
+| --------------------- | ----------------- | ------------------ | ------------------------ |
+| 2017.1.0              | Early Aug 2017    | v1.2017.1.0        | <ul><li>Updating to Unity's beta build.</li><li>3D Keyboard for text entry.</li></ul>|
+| 2017.2.0              | End Sep 2017      | v1.2017.2.0        | <ul><li>Updating master with Windows Mixed Reality support (xR namespace).</li><li>RI Dev_Unity_2017.2.0 into master.</li><li>Toolkit will work on both HoloLens and immersive headsets.</li><li>Windows Mixed Reality motion controller support.</li></ul>|
+| 2017.3.0              | End Dec 2017      | v1.2017.3.0        | <ul><li>360 video player prefabs.</li><li>Scriptable foveated rendering prefabs.</li></ul>|
+### Dev_Unity_2017.2.0 branch
 
-## Please note:
-1. We will not merge this branch into master until we have a publicly available non-beta Unity that supports it and a HoloLens build that works with these new APIs.
-2. You can use this branch with Windows Creators Update builds on your PC and deploy it to Windows Anniversary Update HoloLens flight.
-3. Windows Creators Update flights don’t ship on HoloLens.
+| Target Unity release  | Release timeframe | Branch release tag | Branch pre-release features | Status |
+| --------------------- | ----------------- | ------------------ | --------------------------- | --------------------------- |
+| MRTP9                 | End July 2017     | v1.Dev.MRTP9       | <ul><li>Windows Mixed Reality support for working on both HoloLens and immersive headsets.</li><li>Gamepad support.</li><li>Windows Mixed Reality motion controller support.</li></ul>| [Complete: v1.Dev.MRTP9](https://github.com/Microsoft/HoloToolkit-Unity/releases/tag/v1.Dev.MRTP9) |
+| MRTP13                | Early Aug 2017    | v1.Dev.MRTP13      | <ul><li>Updating to MRTP13.</li><li>Windows Mixed Reality motion controller rendering with glTF format read from WU driver.</li></ul>| [Complete: v1.Dev.MRTP13](https://github.com/Microsoft/HoloToolkit-Unity/releases/tag/v1.Dev.MRTP13) |
+| 2017.2.0              | Mid Aug 2017      | v1.Dev.2017.2.0    | <ul><li>Adapting to Unity's breaking changes of xR namespace and others.</li></ul>| In progress |
+| 2017.2.0              | End Sep 2017      | v1.Dev.2017.2.1    | <ul><li>Merge branch into master.</li></ul>| Not started. |
 
-## MixedRealityToolkit contains the following feature areas:
+# Upcoming Breaking Changes
 
-1. [Boundary](Assets/HoloToolkit/Boundary/README.md)
-2. [Build](Assets/HoloToolkit/Build/README.md)
-3. [Input](Assets/HoloToolkit/Input/README.md)
-4. [Sharing](Assets/HoloToolkit/Sharing/README.md)
-5. [Spatial Mapping](Assets/HoloToolkit/SpatialMapping/README.md)
-6. [Spatial Sound](Assets/HoloToolkit/SpatialSound/README.md)
-7. [Spatial Understanding](Assets/HoloToolkit/SpatialUnderstanding/README.md)
-8. [Utilities](Assets/HoloToolkit/Utilities/README.md)
+- **Renaming HoloToolkit-Unity repository to MixedRealityToolkit-Unity** to align with product direction.
+- Technically **all your checkins and redirect links will continue to work as-is** but we wanted to give a better heads up on this.
+- All other dependent repositories will undergo a similar name change.
+- We are **not breaking toolkit folder names and namespaces at this time.**
+- Instead we are taking a staggered approach for breaking changes based on developer feedback.
 
+| Breaking change description                     | Release timeframe | Notes                    |
+| ----------------------------------------------- | ----------------- | ------------------------ |
+| Rename repository to MixedRealityToolkit-Unity. | Mid Aug 2017      | <ul><li>Recommend you do: $git remote set-url origin new_url.</li><li>Recommend reading: https://help.github.com/articles/renaming-a-repository ; https://github.com/blog/1508-repository-redirects-are-here</li></ul>|
+| Updating toolkit namespace to MixedReality      | Nov 2017          | <ul><li>Update folder names, class names and namespace names post 2017.2.0 release.</li></ul>|
 
-To learn how to add the MixedRealityToolkit to your project see the [Getting Started](GettingStarted.md) guide.
+# Future work planning
+- Updating landing page for the ReadMe.md to help app developers find content better.
+- Updating API documentation using tools like Doxygen and not writing them manually. This is something we will work with all of you on.
+- Update Wiki to host API documentation instead.
+- Move reusable features from [Mixed Reality Design Labs](https://github.com/Microsoft/MRDesignLabs_Unity) project into toolkit.
+
+# Release cadence
+### Master branch
+- **Master branch releases** will align with **major Unity releases marking a release every 3 months**. Please read the [Unity roadmap](https://unity3d.com/unity/roadmap).
+- Each release will be marked as a GitHub [release tag](https://github.com/Microsoft/HoloToolkit-Unity/releases). You can consume this release by:
+	- Using the zip file available in the release notes
+	- Unity packages available in the release notes
+	- Syncing to the specific git tag you would like to lock on.
+- Release tag name convention: v1.Unity release major number.Unity release minor number.Iteration number
+	- For example: For Unity version 2017.1.0 our release tag would be **v1.2017.1.0**
+	- If we marked another release with the same Unity version: **v1.2017.1.1**
+- Unity packages for each release will be published to the Unity asset store.
+- Unity packages for each feature area like Input/SpatialMapping will also be added to the release notes.
+- Academy content will be updated with each major toolkit release.
+
+### Development branches
+- Development branches are great for incubating features before they make their way into master.
+- These branches can be feature work or experimental features.
+- Development branches might not be on the same Unity versions as master.
+- For being merged into Master the dev branch will have to follow the cadence laid out for master.
+- Development branches might choose to mark releases on a faster cadence based on customer/project needs.
+- Recommend marking a development branch tag every 2 weeks as needed to ensure stability before making up to master.
+- Development branches might be deleted once merged into master. If more work is pending, it's ok to continue working in them.
+
+**External\How To** docs folder is meant to help everyone with migrating forward or any simple doubts they might have about the process.
+Please feel free to grow all these sections. We can't wait to see your additions!
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 
 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+# Useful resources on Microsoft Windows Dev Center
+| ![Academy](External/ReadMeImages/icon_academy.png) [Academy](https://developer.microsoft.com/en-us/windows/mixed-reality/academy)| ![Design](External/ReadMeImages/icon_design.png) [Design](https://developer.microsoft.com/en-us/windows/mixed-reality/design)| ![Development](External/ReadMeImages/icon_development.png) [Development](https://developer.microsoft.com/en-us/windows/mixed-reality/development)| ![Community)](External/ReadMeImages/icon_community.png) [Community](https://developer.microsoft.com/en-us/windows/mixed-reality/community)|
+| :--------------------- | :----------------- | :------------------ | :------------------------ |
+| See code examples. Do a coding tutorial. Watch guest lectures.          | Get design guides. Build user interface. Learn interactions and input.     | Get development guides. Learn the technology. Understand the science.       | Join open source projects. Ask questions on forums. Attend events and meetups. |
