實驗性功能 - 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) ,但導致 PR 無法簽入。

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

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

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

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

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

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

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

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

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

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