Experimentelle Features — MRTK2

Einige Features, an denen das MRTK-Team arbeitet, scheinen auf den ersten Blick großen Nutzen zu versprechen, selbst wenn wir die Details noch nicht vollständig implementiert haben. Für diese Arten von Features möchten wir der Community die Chance geben, sie frühzeitig zu sehen. Da sie sich noch in einem frühen Stadium befinden, bezeichnen wir sie als experimentell, um anzuzeigen, dass sie sich noch weiterentwickeln und im Lauf der Zeit Änderungen unterworfen sind.

Was Sie von einem experimentellen Feature erwarten können

Wenn eine Komponente als experimentell gekennzeichnet ist, können Sie Folgendes erwarten:

• Eine Beispielszene zur Veranschaulichung der Verwendung unter dem MRTK/Examples/Experimental Unterordner
• Experimentelle Features verfügen möglicherweise nicht über Dokumente.
• Sie haben wahrscheinlich keine Tests.
• Experimentelle Features können sich ändern.

Richtlinien für experimentelle Features

Experimenteller Code sollte sich in einem separaten Ordner befinden

Experimenteller Code sollte in einen experimentellen Ordner auf oberster Ebene eingefügt werden, gefolgt vom experimentellen Featurenamen. Wenn Sie z. B. versuchen, ein neues Feature FooBar beizutragen, fügen Sie Code in den folgenden Code ein:

• Beispielszenen, Skripts MRTK/Examples/Experimental/FooBar/
• Komponentenskripts, Prefabs werden in MRTK/SDK/Experimental/FooBar/
• Komponenteninspektoren werden in MRTK/SDK/Inspectors/Experimental/FooBar

Wenn Sie Unterordner unter dem experimentellen Featurenamen verwenden, versuchen Sie, die gleiche Ordnerstruktur von MRTK zu Spiegel.

Solver würden beispielsweise unter MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

Behalten Sie Szenen in einem Szenenordner in der Nähe des oberen Bereichs bei: MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

Hinweis

Wir haben in Erwägung gezogen, keinen einzigen Experimentellen Stammordner zu haben und stattdessen Experimental unter zu setzen MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity. Wir haben uns entschieden, ordner an der Basis zu verwenden, um die experimentellen Features einfacher zu entdecken.

Experimenteller Code sollte sich in einem speziellen Namespace befinden

Stellen Sie sicher, dass sich der experimentelle Code in einem experimentellen Namespace befindet, der dem nicht experimentellen Speicherort entspricht. Wenn Ihre Komponente beispielsweise Teil von Solvern in Microsoft.MixedReality.Toolkit.Utilities.Solversist, sollte ihr Namespace sein Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers.

Ein Beispiel finden Sie in diesem PR .

Experimentelle Features sollten über ein [Experimental]-Attribut verfügen

Fügen Sie ein [Experimental] Attribut über einem Ihrer Felder hinzu, damit im Komponenten-Editor ein kleines Dialogfeld angezeigt wird, in dem angegeben wird, dass Ihr Feature experimentell ist und erheblichen Änderungen unterliegt.

Menüs für experimentelle Features sollten unter dem Untermenü "Experimentell" angezeigt werden.

Stellen Sie sicher, dass sich experimentelle Features unter "experimentellen" Untermenüs befinden, wenn Sie Menüs im Editor Befehle hinzufügen. Hier sind einige Beispiele:

Hinzufügen eines Menübefehls der obersten Ebene:

[MenuItem("Mixed Reality Toolkit/Experimental/MyCommand")]
public static void MyCommand()

Hinzufügen eines Komponentenmenüs:

[AddComponentMenu("MRTK/Experimental/MyCommand")]

Dokumentation

Führen Sie die folgenden Schritte aus, um dokumentation für Ihr experimentelles Feature hinzuzufügen:

1. Jede Dokumentation für ein experimentelles Feature sollte in einer readme.md Datei im experimentellen Ordner gespeichert werden. Beispiel: MRTK/SDK/Experimental/PulseShader/readme.md.

2. Fügen Sie unter Featureübersichten einen Link im Abschnitt Experimental unter hinzu Documentation/toc.yml.

Minimieren der Auswirkungen auf MRTK-Code

Obwohl Ihre MRTK-Änderung Ihr Experiment möglicherweise zum Funktionieren bringen kann, könnte sie andere Personen auf eine Weise beeinflussen, die Sie nicht erwarten. Alle Regressionen, die Sie in den MRTK-Kerncode vornehmen, würden dazu führen, dass Ihr Pull Request wiederhergestellt wird.

Versuchen Sie, keine Änderungen in ordnern zu haben, die keine experimentellen Ordner sind. Im Folgenden finden Sie eine Liste von Ordnern, die experimentelle Änderungen aufweisen können:

• MRTK/SDK/Experimentell
• MRTK/SDK/Inspectors/Experimental
• MRTK/Examples/Experimental

Änderungen außerhalb dieser Ordner sollten sehr sorgfältig behandelt werden. Wenn Ihr experimentelles Feature Änderungen am MRTK-Kerncode enthalten muss, sollten Sie MRTK-Änderungen in einen separaten Pull Request aufteilen, der Tests und Dokumentation enthält.

Die Verwendung Ihres experimentellen Features sollte sich nicht auf die Fähigkeit der Benutzer zur Verwendung von Kernsteuerelementen auswirken.

Die meisten Benutzer verwenden sehr häufig kernige UX-Komponenten wie die Schaltfläche, ManipulationHandler und Interactable. Sie werden Ihr experimentelles Feature wahrscheinlich nicht verwenden, wenn sie die Verwendung von Schaltflächen verhindert.

Die Verwendung Ihrer Komponente sollte schaltflächen, ManipulationHandler, BoundingBox oder interagierbar nicht unterbrechen.

Beispiel: In diesem ScrollableObjectCollection-PR konnten Benutzer durch Das Hinzufügen einer ScrollableObjectCollection-Datei die HoloLens-Schaltflächen-Prefabs nicht verwenden. Obwohl dies nicht durch einen Fehler im PR verursacht wurde (sondern einen vorhandenen Fehler offengelegt hat), verhinderte es, dass der PR eingecheckt wurde.

Stellen Sie eine Beispielszene bereit, in der die Verwendung des Features veranschaulicht wird.

Personen müssen sehen, wie Sie Ihr Feature verwenden und testen können.

Geben Sie ein Beispiel unter MRTK/Examples/Experimental/YOUR_FEATURE

Minimieren sichtbarer Fehler des Benutzers in experimentellen Features

Andere verwenden das experimentelle Feature nicht, wenn es nicht funktioniert, es wird nicht zu einem Feature gestuft.

Testen Sie Ihre Beispielszene auf Ihrer Zielplattform, und stellen Sie sicher, dass sie wie erwartet funktioniert. Stellen Sie sicher, dass Ihr Feature auch im Editor funktioniert, damit Benutzer Ihr Feature schnell durchlaufen und sehen können, auch wenn sie nicht über die Zielplattform verfügen.

Graduieren von experimentellem Code in MRTK-Code

Wenn ein Feature am Ende ziemlich viel Verwendet wird, sollten wir es in den KERN-MRTK-Code einteilen. Dazu sollte das Feature über Tests, Dokumentation und eine Beispielszene verfügen.

Wenn Sie bereit sind, das Feature MRTK zu überprüfen, erstellen Sie ein Problem, um Ihren PR zu überprüfen. Der PR sollte alles enthalten, was erforderlich ist, um dies zu einem Kernfeature zu machen: Tests, Dokumentation und eine Beispielszene, die die Verwendung zeigt.

Vergessen Sie außerdem nicht, die Namespaces zu aktualisieren, um den Unterbereich "Experimental" zu entfernen.