實驗性功能 — MRTK2

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")]

文件

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

  1. 實驗性功能的任何檔都應該在實驗資料夾中的檔案中 readme.md 。 例如,MRTK/SDK/Experimental/PulseShader/readme.md。

  2. [功能概觀] 下方的 [ 實驗 性] 區段中 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 所造成,但會公開現有的 Bug) ,但導致 PR 無法簽入。

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

人員必須瞭解如何使用您的功能,以及如何進行測試。

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

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

如果實驗性功能無法運作,其他人將不會使用實驗性功能,也不會從功能開始。

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

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

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

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

此外,別忘了更新命名空間以移除「實驗性」子空間。