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 von einem experimentellen Feature erwartet wird
Wenn eine Komponente experimentell gekennzeichnet ist, können Sie folgendes erwarten:
- Eine Beispielszene, die die Verwendung veranschaulicht, befindet sich im
MRTK/Examples/Experimental
Unterordner - Experimentelle Features verfügen möglicherweise nicht über Dokumente.
- Sie haben wahrscheinlich keine Tests.
- Experimentelle Features unterliegen änderungen.
Experimentelle Featurerichtlinien
Experimenteller Code sollte in einem separaten Ordner leben
Experimenteller Code sollte in einen experimentellen Ordner auf oberster Ebene gehen, gefolgt vom experimentellen Featurenamen. Wenn Sie z. B. versuchen, ein neues Feature FooBar beizutragen, fügen Sie Code in die folgenden Schritte ein:
- Beispielszenen, Skripts gehen in
MRTK/Examples/Experimental/FooBar/
- Komponentenskripts, Prefabs wechseln zu
MRTK/SDK/Experimental/FooBar/
- Komponenteninspektoren gehen zu
MRTK/SDK/Inspectors/Experimental/FooBar
Wenn Sie Unterordner unter dem experimentellen Featurenamen verwenden, versuchen Sie, die gleiche Ordnerstruktur von MRTK zu spiegeln.
Solver würden z. B. untergehen MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs
Behalten Sie Szenen in einem Szenenordner in der Nähe des oberen Rands auf: MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity
Hinweis
Wir haben betrachtet, dass kein einzelner experimenteller Stammordner angezeigt wird und stattdessen Experimental unter dem Wort MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity
gestellt wird. Wir haben beschlossen, mit Ordnern auf der Basis zu wechseln, um die experimentellen Features einfacher zu entdecken.
Experimenteller Code sollte sich in einem speziellen Namespace befinden
Stellen Sie sicher, dass der experimentelle Code in einem experimentellen Namespace lebt, der dem nicht experimentellen Speicherort entspricht. Wenn Ihre Komponente beispielsweise Teil von Solvern ist Microsoft.MixedReality.Toolkit.Utilities.Solvers
, sollte Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers
der Namespace sein.
Sehen Sie sich diese PR für ein Beispiel an.
Experimentelle Features sollten über ein [Experimental]-Attribut verfügen
Fügen Sie ein Attribut oberhalb eines Ihrer Felder hinzu, um im [Experimental]
Komponenten-Editor ein kleines Dialogfeld anzuzeigen, das Ihr Feature erwähnt, experimentell ist und den wesentlichen Änderungen unterliegen.
Menüs für experimentelle Features sollten unter "Experimentelles" Untermenü wechseln
Stellen Sie sicher, dass experimentelle Features unter "experimentelle" Untermenüs zum Hinzufügen von Befehlen zu Menüs im Editor stehen. Hier sind einige Beispiele:
Hinzufügen eines Menübefehls auf oberster 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:
Alle Dokumentationen für ein experimentelles Feature sollten in einer
readme.md
Datei im experimentellen Ordner wechseln. Beispielsweise MRTK/SDK/Experimental/PulseShader/readme.md.Fügen Sie unter "Featureübersichten" einen Link im Abschnitt "Experimentelles" hinzu.
Documentation/toc.yml
Minimieren der Auswirkungen auf MRTK-Code
Während Ihre MRTK-Änderung Ihr Experiment möglicherweise funktioniert, könnte es sich auf andere Personen auswirken, die Sie nicht erwarten. Alle Regressionen, die Sie an den MRTK-Kerncode vornehmen, würden dazu führen, dass Ihre Pull-Anforderung zurückgesetzt wird.
Ziel ist es, null Änderungen in Ordnern zu haben, die nicht in experimentellen Ordnern vorhanden sind. Nachfolgend finden Sie eine Liste mit Ordnern, die experimentelle Änderungen aufweisen können:
- MRTK/SDK/Experimental
- MRTK/SDK/Inspectors/Experimental
- MRTK/Beispiele/Experimentelles
Änderungen außerhalb dieser Ordner sollten sehr sorgfältig behandelt werden. Wenn Ihr experimentelles Feature Änderungen an MRTK-Kerncode enthalten muss, sollten Sie mrTK-Änderungen in eine separate Pull-Anforderung aufteilen, die Tests und Dokumentationen enthält.
Die Verwendung ihres experimentellen Features sollte nicht auf die Fähigkeit von Personen auswirken, Kernsteuerelemente zu verwenden
Die meisten Personen verwenden kernige UX-Komponenten wie schaltfläche, ManipulationHandler und Interagierbar sehr häufig. Sie verwenden wahrscheinlich nicht Ihr experimentelles Feature, wenn sie verhindern, dass sie Schaltflächen verwenden.
Die Verwendung Ihrer Komponente sollte keine Schaltflächen unterbrechen, ManipulationHandler, BoundingBox oder interagierbar sein.
In dieser ScrollableObjectCollection-PR verursacht das Hinzufügen eines ScrollableObjectCollection-Steuerelements dazu, dass Personen die HoloLens-Schaltflächen-Prefabs nicht verwenden können. Obwohl dies nicht durch einen Fehler in der PR verursacht wurde (sondern einen vorhandenen Fehler verfügbar gemacht hat), verhinderte es, dass die PR eingecheckt wird.
Geben Sie eine Beispielszene an, in der veranschaulicht wird, wie Sie das Feature verwenden.
Personen müssen sehen, wie Sie Ihr Feature verwenden und wie sie getestet werden.
Geben Sie ein Beispiel unter MRTK/Beispiele/Experimentelle/YOUR_FEATURE
Minimieren von sichtbaren Fehlern des Benutzers in experimentellen Features
Andere werden das experimentelle Feature nicht verwenden, wenn es nicht funktioniert, wird es nicht auf ein Feature abgestuft.
Testen Sie Ihre Beispielszene auf Ihrer Zielplattform, stellen Sie sicher, dass es wie erwartet funktioniert. Stellen Sie sicher, dass Ihr Feature auch im Editor funktioniert, sodass Personen Ihre Funktion schnell iterieren und anzeigen können, auch wenn sie nicht über die Zielplattform verfügen.
Abschluss des experimentellen Codes in MRTK-Code
Wenn ein Feature sehr viel Verwendet wird, sollten wir es in den Kern-MRTK-Code absteigen. Dazu sollte das Feature Tests, Dokumentation und eine Beispielszene aufweisen.
Wenn Sie bereit sind, das Feature MRTK zu graduieren, erstellen Sie ein Problem, um sich auf Ihre PR zu überprüfen. Die PR sollte alle erforderlichen Dinge umfassen, um dies zu einem Kernfeature zu machen: Tests, Dokumentationen und eine Beispielszene, die die Verwendung anzeigt.
Vergessen Sie auch nicht, die Namespaces zu aktualisieren, um den Unterbereich "Experimental" zu entfernen.