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.unitygestellt 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.Solversder 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:

1. Alle Dokumentationen für ein experimentelles Feature sollten in einer readme.md Datei im experimentellen Ordner wechseln. Beispielsweise MRTK/SDK/Experimental/PulseShader/readme.md.

2. 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.