重大變更 — MRTK2

MRTK 的取用者相依于具有穩定發行對發行 API 介面,以便他們每次都不需要進行重大變更,就能更新 MRTK。

此頁面說明有關 MRTK 中重大變更的目前原則,以及一些長期目標,說明如何更妥善地管理中斷性變更之間的取捨,以及能夠對程式碼進行正確的長期技術變更。

什麼是重大變更?

如果變更符合清單 A中的任何條件,且符合清單 B中的所有條件,則變更是重大變更

列出 A

  • 新增、移除或更新任何介面的任何成員或函式, (或移除/重新命名整個介面) 。
  • 移除、更新 (變更類型/定義,讓類別的任何受保護或公用成員或函式成為私人或內部) 。 (或移除/重新命名整個類別) 。
  • 類別所引發事件順序的變更。
  • ScriptableObject 上任何私用 SerializedField (的重新命名) 或公用屬性, (特別變更設定檔) 。
  • 變更 ScriptableObject 上欄位的類型, (特別變更設定檔) 。
  • 更新至任何類別或介面的命名空間或 asmdefs。
  • 移除預製物件上任何預製物件或移除腳本。

清單 B

  • 有問題的資產位於基礎套件 (,也就是位於下列其中一個資料夾中) :

    • MRTK/Core
    • MRTK/Providers/
    • MRTK/Services/
    • MRTK/SDK/
    • MRTK/Extensions
  • 有問題的資產不屬於實驗命名空間。

重要

任何位於範例套件中的資產 (亦即 MRTK/Examples/ 資料夾的一部分,) 隨時都會變更,因為取用者設計要複製並檢視的資產是「參考實作」,但不屬於核心 API 和資產集的一部分。 實驗命名空間中的資產 (或更普遍地,標示為實驗性) 的功能是在完成所有盡責 (之前發佈的功能,也就是測試、UX 反復專案、檔) ,並提早發佈,以更快取得意見反應。 不過,由於它們沒有測試和檔,而且我們可能尚未關閉所有互動和設計,因此我們會以公開應該假設他們可以和變更 (的狀態發佈它們,也就是修改、完全移除等) 。

如需詳細資訊,請參閱 實驗性功能

由於中斷性變更的介面區非常大,請務必注意,具有絕對規則表示「沒有重大變更」,可能會發生問題,因為有中斷性變更時,可能只能透過中斷性變更來修正。 為了另一種方式,我們真的可以有「沒有重大變更」的唯一方式就是完全沒有變更。

我們的常設原則是盡可能避免進行重大變更,而且只有在變更會累算重要的客戶或架構長期價值時,才這麼做。

重大變更的用途

如果可以完成沒有中斷性變更,且不會危害功能的長期結構和可行性,請勿進行中斷性變更。 如果沒有其他方式,則目前的原則是評估每個個別的重大變更,以瞭解從取得變更的好處是否超過取用者接受變更的成本。 對於值得執行哪些動作,以及通常不會對 PR 或問題討論本身進行哪些事進行討論。

此處可能發生的情況落在數個貯體中:

重大變更會增加值,但可能會以未中斷的方式寫入

例如, 此 PR 新增了一項新功能,一開始是以中斷的方式撰寫,它修改了現有的介面,但接著會重寫功能在功能細分為自己的介面的位置。 這通常是最佳可能的結果。 如果這樣做會危害功能的長期可行性或結構,請勿嘗試強制變更非中斷形式。

重大變更可讓客戶擁有足夠的價值

記錄重大變更是什麼,並提供最佳可能的緩和措施 (,也就是如何移轉的規範性步驟,或更妥善地為客戶) 移轉的工具。 每個版本可能包含少量的變更,這些變更應該一律記載在此 PR中。 如果已經有 2.x.x→2.x+1.x+1 移轉指南,請將指示或工具新增至該檔。如果不存在,請加以建立。

重大變更會增加價值,但客戶感到困難會太高

並非所有類型的中斷性變更都相等, 有些則根據我們的體驗和客戶體驗,對其他人而言會更加麻煩。 例如,對介面的變更可能很麻煩,但如果重大變更是客戶不太可能在過去 (診斷視覺效果系統進行擴充/實作的變更,例如) ,則實際成本可能很低。 不過,如果變更是 ScriptableObject (上欄位的類型,例如,在 MRTK) 的其中一個核心設定檔上,這可能會造成大量的客戶痛。 客戶已經複製預設設定檔,合併/更新設定檔可能非常難以手動 (,亦即,透過合併時間的文字編輯器) ,以及手動重新複製預設設定檔並重新設定所有專案,很可能很難對回歸進行偵錯。

我們必須將這些變更放回架子,直到分支存在,該分支將允許大幅中斷性變更 (,以及提供客戶升級) 的重要價值。 這類分支目前不存在。 在未來的反復專案規劃會議中,我們將檢閱一組「太中斷」的變更/問題,以查看我們是否已達到重大數量,以便一次進行一組全部變更。 請注意,由於我們擁有的工程資源有限,因此啟動「允許所有專案」分支並不具危險性,而且我們必須將測試和驗證分割到這兩個分支。 當分支存在時,必須有清楚的用途和妥善溝通的開始和結束日期。

長期管理重大變更

長期而言,我們應該藉由增加 清單 B中的一組條件來減少重大變更的範圍。接下來 ,清單 A 中的一組專案一律會針對我們視為在「公用 API 介面」中的檔案和資產集進行技術性中斷。我們可以在反復專案 (取得更自由的方式,也就是變更內部實作詳細資料,以便更輕鬆地重構和共用多個類別之間的程式碼,等) 更明確地說明程式碼的哪些部分是官方介面,而不是實作詳細資料。

我們已完成的其中一件事是介紹「實驗性」功能的概念, (它屬於實驗命名空間,它可能沒有測試/檔,而且已公開更新為存在,但可能會移除並更新,而不需警告) 。 這可讓您自由地更快新增新功能來取得先前的意見反應,但不會立即系結至其 API 介面 (,因為我們可能尚未完全思考 API 介面) 。

未來可協助的其他專案範例

  • 內部關鍵字的使用方式。 這可讓我們在自己的元件內共用程式碼, (減少程式碼重複) ,而不會讓外部取用者公開程式碼。
  • (建立「內部」命名空間,也就是 Microsoft.MixedReality.Toolkit.Internal.Utilities) ,我們公開記載該內部命名空間內所包含的任何專案隨時都會變更,而且可以移除等等。這類似于 C++ 標頭程式庫如何使用 ::internal 命名空間來隱藏其實作詳細資料。