重大變更

MRTK 的取用者相依于擁有穩定的發行對發行 API 介面,讓它們可以在不需要每次大量變更的情況下,取得 MRTK 的更新。

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

什麼是重大變更?

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

列出

  • 新增、移除或更新任何介面的任何成員或函數, (或移除/重新命名整個介面) 。
  • 移除、更新 (變更類型/定義,使其成為任何受保護或公用成員或類別功能的私用或內部) 。 (或移除/重新命名整個類別) 。
  • 類別所引發的事件順序變更。
  • 重新命名任何私用 SerializedField (沒有對應的 FormerlySerializedAs 標籤) 或 ScriptableObject 上的公用屬性 (特別是對設定檔) 的變更。
  • 變更 ScriptableObject 上欄位的類型 (特別是) 設定檔的變更。
  • 對任何類別或介面的命名空間或 asmdefs 進行更新。
  • 移除預製專案最上層物件上的任何預製專案或移除腳本。

清單 B

  • 有問題的資產是在基礎封裝中 (也就是在下列其中一個資料夾中) :

    • MRTK/核心
    • MRTK/Providers/
    • MRTK/Services/
    • MRTK/SDK/
    • MRTK/擴充功能
  • 有問題的資產不屬於實驗命名空間。

重要

任何位於範例套件中的資產 (也就是 MRTK/範例/資料夾) 的一部分隨時可能變更,因為資產的設計目的是要將取用者複製和查看為「參考實施」,但不屬於核心的 Api 和資產集。 實驗命名空間中的資產 ((或更多)通常是標示為實驗性) 的功能,就是在完成所有到期的工作之前發佈的專案 (例如測試、UX 反復專案、檔) ,而且會提早發行以取得意見反應。 不過,因為它們沒有測試和檔,而且因為我們可能尚未答對所有互動和設計,所以我們會在 (公開的情況下發布這些互動和設計,也就是修改、完全移除等) 。

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

由於重大變更的介面區非常龐大,因此請務必注意,有一項絕對規則會指出「沒有重大變更」是不可能的,因為可能會有一些問題,只有在有重大變更的情況下,才能以清楚了的方式加以修正。 若要以另一種方式進行,我們可以真正沒有任何重大變更的唯一方法就是完全沒有變更。

我們的長期原則是避免在可能的情況下進行重大變更,而且只有在變更會累積大量客戶或架構長期的價值時才這樣做。

重大變更的用途

如果有可能在沒有重大變更的情況下完成某項作業,而且未危及功能的長期結構和可行性,請不要進行中斷性變更。 如果沒有其他方法,則目前的原則是評估每個個別的重大變更,以瞭解進行變更的好處是否超過吸收變更的取用者成本。 討論有哪些值得進行的工作,以及在 PR 或問題討論方面通常不會發生什麼事。

這裡可能會有幾個值區:

中斷性變更增加了價值,但無法以不中斷的方式寫入

例如, 此 PR 新增了一項新功能,其一開始是以已中斷的方式修改現有的介面,但接著會在功能被視為本身介面的地方重寫。 這通常是最可能的結果。 如果這樣做會危及功能的長期可行性或結構,請不要嘗試強制變更成為不中斷的表單。

中斷性變更為客戶增加了足夠的價值,

記錄重大變更的內容,並提供最佳的緩和措施 (例如,有關如何遷移或更好的工具將自動遷移至客戶) 的規範步驟。 每個版本可能會包含一些重大變更,這些變更應該一律記錄在 此 PR中的檔。 如果已經有2.x → 2.x +1 x + 1 的遷移指南,請在該檔中新增指示或工具。如果不存在,請加以建立。

中斷性變更增加了價值,但客戶的難題會太高

並非所有類型的中斷性變更都是相等的,有些則會根據我們的經驗和客戶體驗,更令人頭痛。 例如,對介面的變更可能很麻煩,但如果中斷性變更是客戶不太可能在過去 (診斷視覺效果系統來擴充/執行,例如) ,則實際成本可能會低到任何東西。 但是,如果變更是 ScriptableObject 上欄位的類型 (例如,在 MRTK) 的其中一個核心設定檔上,這可能會導致大量客戶的難題。 客戶已複製預設設定檔,合併/更新設定檔可能很難手動執行 (也就是在合併時間) 的文字編輯器中,重新複製預設設定檔,並以手動方式重新設定所有專案,很可能會導致難以進行回歸。

這些變更必須放回貨架上,直到存在可大幅中斷變更 (的分支,並提供可讓客戶有理由升級) 的重要價值。 這類分支目前不存在。 在我們未來的反復專案規劃會議中,我們將探討一組變更/問題,也就是「過於中斷」的變更/問題,看看我們是否已達到重大的品質,讓您能夠合理地一次執行一組變更。 請注意,因為我們擁有有限的工程資源,所以啟動「允許所有專案」的分支不會有任何問題,因此我們必須在這兩個專案之間分割測試與驗證。 這類分支的開始和結束日期必須是清楚的用途,且會有妥善傳達的開始和結束日期。

重大變更的長期管理

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

我們已經完成的其中一件事,就是介紹「實驗性」功能 (它在實驗命名空間中的概念,它可能不會有測試/檔,而且會公開 proclaimed 至存在,但可能會移除並更新,而不會發生警告) 。 這可讓您更快速地新增新功能來取得較早的意見反應,但不會立即與 API 介面 (的關聯,因為我們可能尚未完全考慮 API 介面) 。

未來可能會有説明的其他專案範例

  • Internal 關鍵字的使用方式。 如此一來,我們就可以在自己的元件內擁有共用程式碼 (以便減少程式碼重複) ,而不需要對外部取用者公開任何東西。
  • 建立「內部」命名空間 (例如) MixedReality,我們會在其中公開記載該內部命名空間內所含的任何事物,隨時可能會變更,並可加以移除等等。這與 c + + 標頭程式庫使用::內部命名空間來隱藏其實作為詳細資料的方式類似。