Experimentelle Merkmale — 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 soll

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

• Beispielszene, in der die Verwendung veranschaulicht wird, die sich im MRTK/Examples/Experimental Unterordner befindet
• Experimentelle Features haben möglicherweise keine Dokumente.
• Sie haben wahrscheinlich keine Tests.
• Experimentelle Features können geändert werden.

Experimentelle Featurerichtlinien

Experimenteller Code sollte in einem separaten Ordner leben

Experimenteller Code sollte in einen experimentellen Ordner auf oberster Ebene wechseln, gefolgt vom experimentellen Featurenamen. Wenn Sie z. B. versuchen, ein neues Feature FooBar mitzuwirken, fügen Sie Code folgendermaßen ein:

• Beispielszenen, Skripts gehen in MRTK/Examples/Experimental/FooBar/
• Komponentenskripts, Prefabs gehen in MRTK/SDK/Experimental/FooBar/
• Komponenteninspektoren gehen in 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

Szenen in einem Szenenordner in der Nähe des oberen Rands beibehalten: MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

Hinweis

Wir haben als nicht einen einzigen experimentellen Stammordner betrachtet und stattdessen "Experimental" unter "Sagen MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity" gestellt. Wir haben uns entschieden, mit Ordnern auf der Basis zu gehen, 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 der Namespace sein Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers.

Sehen Sie sich diese PR für ein Beispiel an.

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

Fügen Sie ein [Experimental] Attribut oberhalb eines Ihrer Felder hinzu, damit im Komponenten-Editor ein kleines Dialogfeld angezeigt wird, das ihr Feature erwähnt, experimentell ist und erhebliche Änderungen betrifft.

Menüs für experimentelle Features sollten unter "Experimentelles" Untermenü wechseln

Stellen Sie sicher, dass experimentelle Features beim Hinzufügen von Befehlen zu Menüs im Editor unter "experimentelle" Untermenüs 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. Jede Dokumentation für ein experimentelles Feature sollte in einer readme.md Datei im experimentellen Ordner abgelegt werden. Beispielsweise MRTK/SDK/Experimental/PulseShader/readme.md.

2. Fügen Sie unter "Featureübersichten" einen Link im Abschnitt "Experimental" 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, wie Sie nicht erwarten. Alle Regressionen, die Sie an den MRTK-Kerncode vornehmen, führen dazu, dass Ihre Pullanforderung wiederhergestellt wird.

Ziel ist es, keine Änderungen in anderen Ordnern als experimentellen Ordnern zu haben. Nachfolgend finden Sie eine Liste mit Ordnern, die experimentelle Änderungen aufweisen können:

• MRTK/SDK/Experimental
• MRTK/SDK/Inspectors/Experimental
• MRTK/Beispiele/Experimenteller

Ä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 Pullanforderung aufteilen, die Tests und Dokumentationen enthält.

Die Verwendung Ihres experimentellen Features sollte sich nicht auf die Fähigkeit von Personen auswirken, Kernsteuerelemente zu verwenden

Die meisten Benutzer verwenden kernige UX-Komponenten wie schaltfläche, ManipulationHandler und Interagierbar sehr häufig. Sie werden wahrscheinlich ihr experimentelles Feature nicht verwenden, wenn sie verhindern, dass sie Schaltflächen verwenden.

Die Verwendung Ihrer Komponente sollte keine Schaltflächen, Manipulationshandler, BoundingBox oder interagierbar machen.

In dieser ScrollableObjectCollection-PR beispielsweise führte das Hinzufügen einer ScrollableObjectCollection dazu, dass Personen die HoloLens-Schaltfläche 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.

Bereitstellen einer Beispielszene, in der veranschaulicht wird, wie das Feature verwendet wird

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

Geben Sie ein Beispiel unter MRTK/Examples/Experimental/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 zu einem Feature abgeschlossen.

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

Abschluss experimenteller Code in MRTK-Code

Wenn ein Feature zu einem großen Teil verwendet wird, sollten wir es in den kernigen MRTK-Code gliedern. Dazu sollte das Feature Tests, Dokumentationen und eine Beispielszene aufweisen.

Wenn Sie bereit sind, das Feature MRTK zu graduieren, erstellen Sie ein Problem, um Ihre PR zu überprüfen. Die PR sollte alle erforderlichen Dinge enthalten, 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.