Skip to content

Commit 2e1d05c

Browse files
added feature contribution process document and updated contributing.md to link to it.
1 parent 1f5f0ce commit 2e1d05c

File tree

2 files changed

+96
-16
lines changed

2 files changed

+96
-16
lines changed

CONTRIBUTING.md

Lines changed: 25 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,28 @@
11
# Contributing
22

3-
The Mixed Reality Toolkit welcomes contributions from the community.
4-
If you have any questions, please reach out on the [HoloLens forums](https://forums.hololens.com/).
3+
The Mixed Reality Toolkit welcomes contributions from the community. For things like fixing typos and small bug fixes, please follow the following contribution guidelines.
4+
5+
>For feature branch contribution guidelines see the [Feature Contribution Process](./Feature_Contribution_Process.md).
6+
7+
If you have any questions, please reach out on the [HoloLens forums](https://forums.hololens.com/) or the [HoloDevelopers slack](https://holodevelopers.slack.com/).
58

69
# Process
710

8-
1. [Make a proposal](https://github.com/Microsoft/MixedRealityToolkit-Unity/issues)
11+
1. [Open an issue](https://github.com/Microsoft/MixedRealityToolkit-Unity/issues/new/choose)
912
- If you are implementing something from our backlog, you do not need to file a new proposal.
1013
2. Implement the change, including any needed demo scenes and/or unit tests.
11-
3. Start a pull request & address comments.
14+
3. Start a pull request & address any questions or change requests.
1215
4. Merge.
1316

14-
# Proposal
17+
# Proposals
1518

16-
For things like fixing typos and small bug fixes, you can skip this step.
19+
If your change is more than a simple fix or a substantial change, please don't just create a big pull request.
1720

18-
If your change is more than a simple fix, please don't just create a big pull request.
19-
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.
20-
This will let us have a brief discussion about the problem and, hopefully, identify some potential pitfalls before too much time is spent.
21+
Instead, start by [opening a proposal](https://github.com/Microsoft/MixedRealityToolkit-Unity/issues?q=is%3Aopen+is%3Aissue+label%3AProposal) 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 any work is started.
2122

22-
Note: If you wish to work on something that already exists on our backlog, you can use that work item as your proposal.
23+
If you're proposing a completely new feature (or a new platform support) please follow the [Feature Contribution Process](./Feature_Contribution_Process.md).
24+
25+
>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.
2326
2427
# Implementation
2528

@@ -38,21 +41,27 @@ Note: If you wish to work on something that already exists on our backlog, you
3841

3942
The Mixed Reality Toolkit provides the following forms of documentation.
4043

41-
- API
44+
### APIs
45+
4246
This documentation is generated from the product code and is reviewed as part of **all** pull requests.
43-
- Conceptual
47+
48+
### Conceptual
49+
4450
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.
45-
- Readme.md files
46-
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.
51+
52+
### Readme files
53+
54+
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.
4755

4856
## Supported Platforms
4957

50-
The Mixed Reality Toolkit supports the following mixed reality (AR/VR/XR) platforms.
58+
The Mixed Reality Toolkit supports the following mixed reality (AR/VR/XR) platforms:
5159

60+
- Windows Standalone
61+
- OpenVR
5262
- Windows Mixed Reality
5363
- Immersive devices
5464
- Microsoft HoloLens
55-
- OpenVR
5665

5766
# Pull request
5867

Feature_Contribution_Process.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Feature Contribution Process
2+
3+
Adding features to the Mixed Reality Toolkit is split up into a few iteration steps, so maintainers can have time to review and and ensure the process goes smoothly.
4+
5+
# Feature Requirements
6+
7+
Features must have the following:
8+
9+
* Assembly Definitions for code outside of the `MixedRealityToolkit/_Core` folder.
10+
* This ensures features are self-contained and have no dependencies to other features.
11+
* Be defined using an interface found in `MixedRealityToolkit/_Core/definitions/<FeatureName>System`.
12+
* A feature's concrete manager implementation should inherit directly from `BaseManager` or `MixedRealityEventManager` if they will raise events.
13+
* A feature's concrete manager implementation should setup and verify scene is ready for that system to use in `Initialize`.
14+
* A feature's concrete manager should also clean up after themselves removing anything created in the scene in `Destroy`.
15+
* Features should have a configuration profile that derives from a scriptable object.
16+
* If the feature is proposed to be a core feature of the Mixed Reality Toolkit, the profile must be accessible in the Main Configuration Profile.
17+
* Be registered with the Mixed Reality Manager.
18+
* If the feature is a core feature, this should be hard coded into the `MixedRealityManager` and added to the `MixedRealityConfigurationProfile`.
19+
* This includes being able to specify a concrete implementation via dropdown using `SystemType`.
20+
* A default configuration profile located in `MixedRealityToolkit-SDK/Profiles` and be assigned in the default configuration profile for the Mixed Reality Manager
21+
* If this feature is **not** a core feature, then it must be registered using the component configuration profile and implement `IMixedRealityComponent`.
22+
* Have a default implementation located in `MixedRealityToolkit-SDK/Features/<FeatureName>`
23+
24+
# Process
25+
26+
1. [Open a Proposal and related Tasks](#proposal)
27+
2. [Submit an Architecture Draft or Outline](#architecture-draft)
28+
3. [Submit final Architecture documentation](#architecture-documentation)
29+
4. [Implement Core feature interfaces and event datum (if applicable)](#core-implementation)
30+
5. [Implement SDK components](#sdk-implementation)
31+
6. [Implement Examples](#example-implementation)
32+
33+
## Proposal
34+
35+
Start by opening a proposal 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.
36+
37+
New Proposals will be reviewed and discussed during our weekly ship room meetings. If a proposal is accepted, then supplemental tasks will be created and assigned.
38+
39+
## Architecture Draft
40+
41+
The first task will generally 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.
42+
43+
* The draft must be easy to consume with key areas highlighted.
44+
* The draft must include a list of the proposed core interfaces, configuration profiles, and event datum.
45+
* The draft must include a simple graphic of the proposed architecture.
46+
47+
>TODO: Add link to architecture draft template
48+
49+
Once the draft is completed, a pull requests can be made against the newly created feature branch for review by maintainers.
50+
51+
## Architecture Documentation
52+
53+
Once the draft architectural document is accepted and merged into the feature branch, additional pull requests can be made to expand and flesh out the final document.
54+
55+
>TODO: Add link to architecture template
56+
57+
Once the architecture document is approved, then the first code submissions can be made.
58+
59+
## Core Implementation
60+
61+
Now work can be done to implement the interfaces, configuration profiles, and event data that will be part of the the Mixed Reality Toolkit's core framework.
62+
63+
>If needed, the architectural document can be updated to align with any changes to the implementation.
64+
65+
## SDK Implementation
66+
67+
Once the core interfaces and events are finished, then work on the SDK components can start.
68+
69+
## Example Implementation
70+
71+
Once the SDK components are finished, then any examples can be updated and added.

0 commit comments

Comments
 (0)