重大變更 - 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 命名空間來隱藏其實作詳細資料。