Experimentelle Features — MRTK2

Einige Features, an denen das MRTK-Team arbeitet, scheinen einen großen Anfangswert zu haben, auch wenn wir die Details noch nicht vollständig ausgearbeitet haben. Für diese Arten von Features möchten wir, dass die Community die Möglichkeit erhält, sie frühzeitig zu sehen. Da sie früh im Zyklus sind, bezeichnen wir sie als experimentell, um darauf hinzuweisen, dass sie sich noch weiterentwickeln und im Laufe der Zeit Änderungen unterliegen.

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 verfügen wahrscheinlich nicht über 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 gefolgt vom Namen des experimentellen Features abgelegt werden. Wenn Sie beispielsweise versuchen, ein neues Feature FooBar beizutragen, fügen Sie Code in den folgenden Code ein:

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

Wenn Sie Unterordner unter dem Namen des experimentellen Features verwenden, versuchen Sie, die gleiche Ordnerstruktur wie MRTK zu Spiegel.

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

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

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 [Experimentell]-Attribut verfügen

Fügen Sie ein [Experimental] Attribut oberhalb eines Ihrer Felder hinzu, damit im Komponenten-Editor ein kleines Dialogfeld angezeigt wird, in dem darauf hingewiesen wird, dass Ihr Feature experimentell ist und bedeutenden Ä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 ein paar 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 gespeichert werden. Beispiel: MRTK/SDK/Experimental/PulseShader/readme.md.

2. Fügen Sie unter Featureübersichten einen Link im Abschnitt Experimentell 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 im MRTK-Kerncode vornehmen, führen dazu, dass Ihr Pull Request wiederhergestellt wird.

Versuchen Sie, keine Änderungen in anderen Ordnern als experimentellen Ordnern vorzunehmen. Im Folgenden finden Sie eine Liste der Ordner, die experimentelle Änderungen aufweisen können:

• MRTK/SDK/Experimentell
• MRTK/SDK/Inspectors/Experimental
• MRTK/Beispiele/Experimentell

Ä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 von Personen auswirken, Kernsteuerelemente zu verwenden.

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 es verhindert, dass sie Schaltflächen verwenden.

Die Verwendung Ihrer Komponente sollte keine Schaltflächen, ManipulationHandler, BoundingBox oder interagierbar unterbrechen.

In dieser ScrollableObjectCollection-PR konnte beispielsweise durch das Hinzufügen einer ScrollableObjectCollection-Datei die HoloLens-Schaltflächen-Prefabs nicht verwendet werden. Obwohl dies nicht durch einen Fehler im PR verursacht wurde (sondern einen vorhandenen Fehler offengelegt hat), wurde verhindert, 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 wie sie es testen können.

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

Minimieren sichtbarer Fehler durch Benutzer in experimentellen Features

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

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.

Abschluss von experimentellem Code in MRTK-Code

Wenn ein Feature am Ende sehr 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 graduieren, erstellen Sie ein Problem, gegen das Sie Ihren PR überprüfen können. Der PR sollte alle Dinge enthalten, die erforderlich sind, 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 "Experimentell" zu entfernen.