實驗性功能 - MRTK2

發行項
07/12/2023

MRTK 小組所處理的某些功能似乎有許多初始價值，即使我們尚未完全瞭解詳細資料也一樣。針對這些類型的功能，我們希望社群有機會提早看到它們。因為它們在週期早期，所以我們會將它們標記為實驗性，以指出它們仍在演進，而且可能會隨著時間而變更。

實驗性功能預期會發生什麼事

如果元件標示為實驗性，您可以預期下列專案：

示範使用方式的範例場景，位於子資料夾底下 MRTK/Examples/Experimental
實驗性功能可能沒有檔。
他們可能沒有測試。
實驗性功能可能會變更。

實驗性功能指導方針

實驗性程式碼應該位於不同的資料夾中

實驗性程式碼應該進入最上層的實驗性資料夾，後面接著實驗性功能名稱。例如，如果嘗試貢獻新功能 FooBar，請將程式碼放入下列各項：

範例場景，腳本會進入 MRTK/Examples/Experimental/FooBar/
元件腳本，預製專案會進入 MRTK/SDK/Experimental/FooBar/
元件偵測器進入 MRTK/SDK/Inspectors/Experimental/FooBar

在實驗性功能名稱下使用子資料夾時，請嘗試鏡像 MRTK 的相同資料夾結構。

例如，解算器會進入 MRTK/SDK/Experimental/FooBar/Features/Utilities/Solvers/FooBarSolver.cs

將場景保留在靠近頂端的場景資料夾中： MRTK/Examples/Experimental/FooBar/Scenes/FooBarExample.unity

注意

我們考慮沒有單一實驗性根資料夾，而是將實驗性置於假設 MRTK/Examples/HandTracking/Scenes/Experimental/HandBasedMenuExample.unity 之下。我們決定在基底使用資料夾，讓實驗性功能更容易探索。

實驗性程式碼應位於特殊命名空間中

請確定實驗性程式碼位於符合非實驗位置的實驗命名空間中。例如，如果您的元件是位於 Microsoft.MixedReality.Toolkit.Utilities.Solvers 的解算器一部分，其命名空間應該是 Microsoft.MixedReality.Toolkit.Experimental.Utilities.Solvers 。

如需範例，請參閱此 PR 。

實驗性功能應具有 [實驗性] 屬性

[Experimental]在其中一個欄位上方新增屬性，讓提及您功能的元件編輯器中出現小型對話方塊是實驗性的，而且可能會有重大變更。

在編輯器中將命令新增至功能表時，請確定實驗性功能位於「實驗性」子功能表之下。以下是一些範例：

新增最上層功能表命令：

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

新增元件功能表：

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

文件

請遵循下列步驟來新增實驗性功能的檔：

實驗性功能的任何檔都應該在 readme.md 實驗性資料夾中的檔案中。例如，MRTK/SDK/Experimental/PulseShader/readme.md。
在 [功能概觀 ] 下方的 [ 實驗性] 區段中 Documentation/toc.yml 新增連結。

將對 MRTK 程式碼的影響降到最低

雖然您的 MRTK 變更可能會讓您的實驗能夠運作，但可能會以您不預期的方式影響其他人。您對 MRTK 核心程式代碼所做的任何回歸，都會導致提取要求還原。

目標是在實驗性資料夾以外的資料夾中零變更。以下是可以有實驗性變更的資料夾清單：

MRTK/SDK/實驗性
MRTK/SDK/Inspectors/Experimental
MRTK/範例/實驗性

這些資料夾以外的變更應該非常謹慎地處理。如果您的實驗性功能必須包含 MRTK 核心程式代碼的變更，請考慮將 MRTK 變更分割成包含測試和檔的個別提取要求。

使用實驗性功能並不會影響人員使用核心控制項的能力

大部分的人都會使用核心 UX 元件，例如按鈕、ManipulationHandler 和 Interactable 非常頻繁。如果實驗性功能防止它們使用按鈕，它們可能會無法使用您的實驗性功能。

使用您的元件不應該中斷按鈕、ManipulationHandler、BoundingBox 或可互動。

例如，在此 ScrollableObjectCollection PR中，新增 ScrollableObjectCollection 會導致使用者無法使用 HoloLens 按鈕預製專案。雖然這並非由 PR (中的錯誤所造成，但會公開現有的 Bug) ，但導致 PR 無法簽入。

提供示範如何使用功能的範例場景

人員需要瞭解如何使用您的功能，以及如何進行測試。

在 MRTK/Example/Experimental/YOUR_FEATURE下提供範例

將實驗性功能中的使用者可見瑕疵降到最低

如果實驗性功能無法運作，其他人就不會使用實驗性功能，也不會升級為特徵。

在目標平臺上測試您的範例場景，確定其如預期般運作。請確定您的功能也適用于編輯器，讓人員可以快速反復查看您的功能，即使他們沒有目標平臺也一樣。

將實驗性程式碼轉換成 MRTK 程式碼

如果功能最後看到相當多的使用，則我們應該將它升為核心 MRTK 程式碼。若要這樣做，此功能應該會有測試、檔和範例場景。

當您準備好將功能 MRTK 定型時，請建立問題以簽入您的 PR。 PR 應該包含讓此成為核心功能所需的所有專案：測試、檔，以及顯示使用方式的範例場景。

此外，別忘了更新命名空間以移除「Experimental」子空間。

共用方式為