Merge pull request #2812 from StephenHodgson/vNEXT-FeatureProcessDocumentation

Feature process documentation and contribution update

Author: SimonDarksideJ

CONTRIBUTING.md

@@ -1,70 +1,106 @@
 # Contributing
 
-The Mixed Reality Toolkit welcomes contributions from the community. 
-If you have any questions, please reach out on the [HoloLens forums](https://forums.hololens.com/).
+The Mixed Reality Toolkit (MRTK) welcomes contributions from the community. Whether it is for a minor change like fixing typos and small bug fixes, or a new feature or component.
 
-# Process
+For larger submissions, we have drafted contribution guidelines to ensure a smooth process and a good quality of code and documentation, so please be sure to review the  [Feature Contribution guidelines / Process](./Feature_Contribution_Process.md).
 
-1. [Make a proposal](https://github.com/Microsoft/MixedRealityToolkit-Unity/issues)
-    - If you are implementing something from our backlog, you do not need to file a new proposal.
-2. Implement the change, including any needed demo scenes and/or unit tests.
-3. Start a pull request & address comments.
-4. Merge.
+All changes be they small or large, need to adhere to the [MRTK Coding Standards](/CodingGuidelines.md), so please ensure you are familiar with these while developing to avoid delays when the change is being reviewed.
 
-# Proposal
+If you have any questions, please reach out on the [HoloLens forums](https://forums.hololens.com/) or the [HoloDevelopers slack](https://holodevelopers.slack.com/).
 
-For things like fixing typos and small bug fixes, you can skip this step.
+# Submission process
+We provide several paths to enable developers to contribute to the Mixed Reality Toolkit, all starting with [creating a new Issue](https://github.com/Microsoft/MixedRealityToolkit-Unity/issues/new/choose)
 
-If your change is more than a simple fix, please don't just create a big pull request. 
-Instead, start by [opening an issue](https://github.com/Microsoft/MixedRealityToolkit-Unity/issues) describing the problem you want to solve and how you plan to approach the problem. 
-This will let us have a brief discussion about the problem and, hopefully, identify some potential pitfalls before too much time is spent.
+![](External/ReadMeImages/issue_selection_prompt.png)
 
-Note:  If you wish to work on something that already exists on our backlog, you can use that work item as your proposal.
+From here you can either:
 
-# Implementation
+* **Open a new issue** - telling of us a bug or issue with the project you are facing.
+> We recommend discussing issues in the [HoloDevelopers slack](https://holodevelopers.slack.com/) channel first to ensure it's an issue with the MRTK.
+
+* **Raise a new Feature request** - some missing feature that you really need, or have even implemented your self that you would like to see added to the project
+
+* **Create a new Task for the Mixed Reality vNext project** - defining a new feature or component for the next generation of the Mixed Reality Toolkit
+
+
+# Creating proposals
+
+To ensure a smooth process when contributing new fixes or features, it's key that you start your journey by creating one of the issue types listed above.
+
+Start by [opening a proposal](https://github.com/Microsoft/MixedRealityToolkit-Unity/issues/new/choose) describing the change you want to make and how your proposed implementation, or simply the issue you are facing. This will enable us have a brief discussion about the proposal and, hopefully, identify some potential pitfalls before any work is started.
+
+If you're proposing a completely new feature (or a new platform support) please follow the [Feature Contribution Process](./Feature_Contribution_Process.md).
+
+>Note:  If you wish to work on something that already exists on our backlog, you can use that work item as your proposal. Be sure to also comment on the task notifying maintainers that you're working towards completing it.
+
+# Beginning development
+Working with Git, the contribution process is quite simple (provided you have installed a good Git Client such as TortoiseGit or SourceTree)
+
+> If you are new to to the Git workflow, [check out this tutorial on Pluralsight](https://www.pluralsight.com/blog/software-development/github-tutorial)
+
+To get started, simply follow these steps
 
 1. Fork the repository. Click on the "Fork" button on the top right of the page and follow the flow.
 2. Create a branch in your fork (off of the [mrtk_development](https://github.com/microsoft/mixedrealitytoolkit-unity/tree/mrtk_development) branch) to make it easier for you to isolate your fork.
+> for the legacy HoloToolkit use the [htk_development](https://github.com/Microsoft/MixedRealityToolkit-Unity/tree/htk_development) branch
 3. Instructions for getting the project building and running the tests are in the [README](README.md). 
-4. Make small and frequent commits that include tests which could be a unity scene showing usage of your feature.
+4. Make **small and frequent** commits that include tests which could be a unity scene showing usage of your feature.
 5. Make sure that all the tests continue to pass.
 6. Follow the [Coding Guidelines](/CodingGuidelines.md).
 7. Ensure the code and feature(s) are documented as describred in the [Documentation Guidelines](/DocumentationGuidelines.md).
 8. Ensure the code works as intended on all [platforms](#supported-platforms).
     - For Windows UWP projects, your code must be [WACK compliant](https://developer.microsoft.com/en-us/windows/develop/app-certification-kit). To do this, generate a Visual Studio solution, right click on project; Store -> Create App Packages. Follow the prompts and run WACK tests. Make sure they all succeed.
 9. Update the [documentation](#update-documentation) with additional information as needed.
 
-## Update Documentation
-
-The Mixed Reality Toolkit provides the following forms of documentation.
 
-- API
-This documentation is generated from the product code and is reviewed as part of **all** pull requests.
-- Conceptual
-Conceptual documentation is hosted on https://docs.microsoft.com/en-us/windows/mixed-reality. Please submit our changes via Pull Request at https://github.com/MicrosoftDocs/mixed-reality.
-- Readme.md files
-As part of your pull request, please update (or create) the Readme.md file in the appropriate feature folder. This will allow GitHub users to gain a high-level understanding of your new feature.
-
-## Supported Platforms
-
-The Mixed Reality Toolkit supports the following mixed reality (AR/VR/XR) platforms.
-
-- Windows Mixed Reality
-    - Immersive devices
-    - Microsoft HoloLens
-- OpenVR
 
 # Pull request
-
-Start a GitHub pull request to merge your topic branch into the [mrtk_development](https://github.com/microsoft/mixedrealitytoolkit-unity/tree/mrtk_development) branch. 
-> If you are a Microsoft employee and are not a member of the [Microsoft organization on GitHub](https://github.com/Microsoft), please link your Microsoft and GitHub accounts on corpnet by visiting [Open Source at Microsoft](https://opensource.microsoft.com/) before you start your pull request. There's some process stuff you'll need to do ahead of time.
+Once you have created your change, it's time to submit a Pull Request (PR) back to the project.  Please ensure all PR's are small and concise, DO NOT include other files / changes not related to the subject of the PR 
+> e.g. Don't update the *projectversion.txt* when you are making changes or adding a button
 
 If you haven't contributed to a Microsoft project before, you may be asked to sign a [contribution license agreement](https://cla.microsoft.com/). 
 A comment in the PR will let you know if you do.
 
+> If you are a Microsoft employee and are not a member of the [Microsoft organization on GitHub](https://github.com/Microsoft), please link your Microsoft and GitHub accounts on corpnet by visiting [Open Source at Microsoft](https://opensource.microsoft.com/) before you start your pull request. There's some process stuff you'll need to do ahead of time.
+
+When you are ready:
+* Start a GitHub pull request to merge your topic branch targetting the [mrtk_development](https://github.com/microsoft/mixedrealitytoolkit-unity/tree/mrtk_development) branch. 
+* Ensure you fill in all details required by the Pull Request template, ensuring you reference any Issue / Feature Request or Task the PR relates to.
+* Validate that you are only checking in files / changes related to the PR
+* Check your documentation is up to date and included (unless submitted in a previous PR)
+
+
 The project maintainers will review your changes. We aim to review all changes within three business days.
-Address any review comments, push to your topic branch, and post a comment letting us know that there's new stuff to review.
+Please address any review comments, push to your topic branch, and post a comment letting us know that there's new stuff to review.
+> All PR's submitted to the project will also be vetted according to the [MRTK coding standards guide](./CodingGuidelines.md), so please review these before submitting your PR to ensure a smooth process.
 
 # Merge
 
-If the pull request review goes well, a project maintainer will merge your changes. Thank you for helping improve the Mixed Reality Toolkit!
+If the pull request review goes well, a project maintainer will merge your changes. Thank you for helping improve the Mixed Reality Toolkit!
+
+# Documentation Requirements
+
+The Mixed Reality Toolkit requires the following forms of documentation for any new feature or component.  Also ensure if you are simply patching / fixing an existing feature that the documentation is also updated to match.
+
+### APIs
+
+This documentation is generated from the product code and is reviewed as part of **all** pull requests.
+
+### Conceptual
+
+Conceptual documentation is hosted on https://docs.microsoft.com/en-us/windows/mixed-reality. Please submit your changes via Pull Request at https://github.com/MicrosoftDocs/mixed-reality.
+
+### Readme files
+
+As part of your pull request, please update (or create) the Readme markdown file in the appropriate feature folder. This will allow GitHub users to gain a high-level understanding of your new feature.
+
+## Supported Platforms
+
+The Mixed Reality Toolkit supports the following mixed reality (AR/VR/XR) platforms:
+
+- Windows Standalone
+    - OpenVR
+- Universal Windows Platform
+    - Standalone PC
+    - Windows Mixed Reality Immersive devices
+    - Microsoft HoloLens

External/ReadMeImages/issue_selection_prompt.png

@@ -0,0 +1,107 @@
+# Feature Contribution Process
+
+Adding features to the Mixed Reality Toolkit (MRTK) is split up into a few iteration steps, so maintainers can have time to review and and ensure the process goes smoothly. Please be sure to review the list of [feature requirements](#new-feature-requirements) before you get started.
+
+# Process
+The following process has been drafted to ensure all new work complies to the updated standards and architecture defined for the MRTK, this has been defined as:
+
+1. [Open a new Proposal and related Tasks](#new-proposal)
+2. [Submit an Architecture Draft or Outline](#architecture-draft)
+3. [Review and finalize the Architecture documentation](#architecture-documentation)
+4. [Submit a PR implementing the Core feature interfaces and event datum (if applicable)](#core-implementation)
+5. [Submit a PR Implementing any required SDK components](#sdk-implementation)
+6. [Submit a PR Implementing feature demos or full scale Examples](#example-implementation)
+
+## New Proposal
+
+ Start by opening a new Proposal or Task describing the feature or the problem you want to solve. Describe the approach and how it fits into the version of the Mixed Reality Toolkit you're targeting. This will enable everyone have a discussion about the proposal and, hopefully, identify some potential pitfalls before any work is started.
+
+ New Proposals will be reviewed and discussed during our weekly ship room meetings and if a proposal is accepted, supplemental tasks will then be created and assigned.
+
+## Architecture Draft
+
+The first task once the initial proposal has been accepted, will be to draft the initial architecture document for the feature or work to be done. This document should typically be one or two pages long and include a high level overview of the feature and how it will relate to other parts of the Mixed Reality Toolkit.
+
+* The draft must be easy to consume with key areas highlighted.
+* The draft must include a list of the proposed core interfaces, configuration profiles, and event datum.
+* The draft must include a simple graphic of the proposed architecture.
+
+Ensure that the architecture of the feature complies with the [New Feature Requirements](#new-feature-requirements) set out by the Core MRTK architecture.
+
+>TODO: Add link to architecture draft template
+
+Once the draft is completed, this can be appended to the Proposal / Task issue on GitHub for final public review.
+
+## Architecture Documentation
+
+Once the draft architecture is accepted, additional pull requests can be made to submit the final full architecture documents to the repository.
+
+>TODO: Add link to the full architecture template
+
+Once the architecture document is approved, only then can the first code submissions can be made.
+
+Development can begin in your own private branch and complete as normal, however, the PR's submitted back to the core MRTK project should be submitted in stages to ensure the review and approval is as smooth as it can be (and ensure core changes do not impact other features)
+
+## Core Implementation
+
+The initial work that should be submitted, is to implement:
+
+* Definitions
+* Interfaces
+* Configuration profiles
+* Event data
+
+> If needed, the architectural document can be updated to align with any changes to the implementation.
+
+Please ensure that all existing Unit Tests and any new tests are all passing prior to submission.
+
+## SDK Implementation
+
+Once the core interfaces and events are merged in to development, work can then be submitted for the SDK components.  Adding the concrete implementation of the feature and testing against the supported platforms and unit tests.
+
+## Example Implementation
+
+Once the SDK components are merged, then any demo scenes or updates to the example scenes can be submitted.
+
+* Demos are for specific feature highlighting and demonstration
+* Examples are full working scene learning examples
+
+# New Feature Requirements
+
+Most feature implementations can be broken down into 3 main parts:
+
+1. [The Feature Manager](#manager-implementation-requirements)
+2. [The Event Data](#event-data-implementation-requirements) (Optional)
+3. [The Feature Handler](#handler-implementation-requirements) (Optional)
+
+## Manager Implementation Requirements
+
+* Assembly Definitions for code outside of the `MixedRealityToolkit/_Core` folder.
+    * This ensures features are self-contained and have no dependencies to other features.
+    * This only applies to `MixedRealityToolkit` folder.
+* Be defined using an interface found in `MixedRealityToolkit/_Core/definitions/<FeatureName>System`.
+* A feature's concrete manager implementation should inherit directly from `BaseManager` or `MixedRealityEventManager` if they will raise events.
+* A feature's concrete manager implementation should setup and verify scene is ready for that system to use in `Initialize`.
+* A feature's concrete manager should also clean up after themselves removing anything created in the scene in `Destroy`.
+* Be registered with the Mixed Reality Manager.
+    * If the feature is a core feature, this should be hard coded into the `MixedRealityManager` and added to the `MixedRealityConfigurationProfile`.
+        * This includes being able to specify a concrete implementation via dropdown using `SystemType`.
+        * Features should have a configuration profile that derives from a scriptable object.
+        * A default configuration profile located in `MixedRealityToolkit-SDK/Profiles` and be assigned in the default configuration profile for the Mixed Reality Manager
+    * If this feature is **not** a core feature, then it must be registered using the component configuration profile and implement `IMixedRealityComponent`.
+* Have a default implementation located in `MixedRealityToolkit-SDK/Features/<FeatureName>`
+* Events that can be raised with the system should be defined in the interface, with all the required parameters for initializing the event data.
+
+## Event Data Implementation Requirements
+The Event Data defines exactly what data the handler is expected to receive from the event.
+
+* All Event Datum for the feature should be defined in `MixedRealityToolkit/_Core/EventDatum/<FeatureName>`.
+* All new Event Data classes should inherit from `GenericBaseEventData`
+
+## Handler Implementation Requirements
+
+The Handler Interface defines each event a component should be listening for and the types of data passed. End users will implement the interface to execute logic based on the event data received.
+
+* Handler interfaces should be defined in `MixedRealityToolkit/_Core/Interfaces/<FeatureName>System/Handlers`.
+* Handler interfaces should inherit from `UnityEngine.EventSystems.IEventSystemHandler`
+* Opt-in by default. To receive events from the system, the handler will need to register itself with the system to receive those events.