Změny způsobující chyby

Spotřebitelé MRTK závisí na tom, jestli mají stabilní plochu rozhraní API pro uvolnění verzí, aby mohli pokaždé aktualizovat MRTK, aniž by museli pokaždé provádět velké změny.

Tato stránka popisuje naše aktuální zásady týkající se průlomových změn v MRTK spolu s některými dlouhodobými cíli, které vám pomohou lépe spravovat kompromisy mezi udržením závažných změn a jejich správnými technickými změnami v kódu.

Co je zásadní změna?

Změna je zásadní změna, pokud splňuje některou z podmínek v seznamu a a splňuje všechny podmínky v seznamu B .

Seznam A

  • Přidání, odebrání nebo aktualizace libovolného člena nebo funkce libovolného rozhraní (nebo odebrání/přejmenování celého rozhraní).
  • Odebrání, aktualizace (Změna typu/definice, vytvoření soukromého nebo interního) libovolného chráněného nebo veřejného člena nebo funkce třídy. (nebo odebrání/přejmenování celé třídy).
  • Změna pořadí událostí vyvolaných třídou.
  • Přejmenování jakýchkoli privátních SerializedField (bez odpovídající značky FormerlySerializedAs) nebo veřejné vlastnosti na ScriptableObject (zejména změny v profilech).
  • Změna typu pole na ScriptableObject (zejména změny v profilech).
  • Aktualizuje obor názvů nebo asmdefs libovolné třídy nebo rozhraní.
  • Odebrání všech Prefab nebo odebrání skriptu na objektu nejvyšší úrovně Prefab.

Seznam B

  • Dotyčný Asset je v balíčku Foundation (tj. je v jedné z následujících složek):

    • MRTK/jádro
    • MRTK/zprostředkovatelé/
    • MRTK/služby/
    • MRTK/SDK/
    • MRTK/rozšíření
  • Příslušný prostředek nepatří do experimentálního oboru názvů.

Důležité

Jakékoli assety, které jsou umístěny v balíčku Examples (například část MRTK/Examples/Folder), se mohou kdykoli změnit, protože prostředky, které jsou určeny k kopírování a prohlížení uživateli jako "referenční implementace", ale nejsou součástí základní sady rozhraní API a prostředků. Prostředky v experimentálním oboru názvů (nebo obecně se jedná o funkce označené jako experimentální) jsou ty, které se publikují před všemi podšpičkami (tj. testy, iterací uživatelského rozhraní, dokumentace) a jsou veřejně publikované, aby získali zpětnou vazbu dřív. Vzhledem k tomu, že nemají testy a dokumentaci a protože nejspíš nejsi všechny interakce a návrhy, zveřejňujeme je ve stavu, ve kterém by veřejnost měla předpokládat, že se můžou a budou měnit (tj. budou se měnit, kompletně odebrány atd.).

Další informace najdete v tématu experimentální funkce .

Vzhledem k tomu, že oblast povrchu pro zásadní změny je velmi velká, je důležité si uvědomit, že mají absolutní pravidlo, které by znamenalo, že "žádné nezávažné změny" by nebylo možné – může dojít k problémům, které mohou být vyřešeny SANE způsobem pomocí zásadní změny. Pro jiný způsob je jediným způsobem, jak bychom mohli mít "žádné zásadní změny", neudělat žádné změny.

Naším cílem je vyhnout se provádění podstatných změn, pokud je to možné, a tak učinit jenom v případě, že by změna znamenala značnou dlouhodobou hodnotu zákazníka nebo Frameworku.

Co dělat v případě nejnovějších změn

Pokud je možné provést něco bez zásadní změny a bez narušení dlouhodobé struktury a životaschopnosti funkce, neprovádějte zásadní změnu. Pokud neexistuje žádný jiný způsob, aktuální zásada je vyhodnotit každou jednotlivou změnu, abyste zjistili, jestli výhoda změny převyšuje náklady na spotřebitele, který změnu provedl. Diskuze o tom, co stojí, a co není obvykle potřeba na diskusi o žádosti o přijetí změn nebo o problému.

Co se může stát, patří do několika kontejnerů:

Zásadní změna přidá hodnotu, ale mohla by být zapsána způsobem, který není průlom

Například Tato žádost o přijetí změn přidala novou funkci, která byla napsána způsobem, který byl porušen – změnila existující rozhraní, ale byla poté přepsána tam, kde byla funkce rozdělena jako své vlastní rozhraní. To je obvykle nejlepší možný výsledek. Nepokoušejte se vynutit změnu v nerušeném tvaru, pokud by by to mohlo ohrozit dlouhodobou životaschopnost nebo strukturu této funkce.

Zásadní změna přičítá k zákazníkovi dostatečnou hodnotu, kterou dělá.

Zdokumentujte, jaké jsou zásadní změny, a poskytněte nejlepší možnou zmírňaci (tj. doporučený postup pro migraci nebo lepší nástroj, který se bude automaticky migrovat pro zákazníka). Každé vydání může obsahovat malé množství změn, které se přerušují – ty by měly být vždy popsány v dokumentaci, jak bylo provedeno v tétožádosti o přijetí změn. Pokud již existuje 2. x. x → 2. x +1. x + 1 Průvodce migrací, přidejte do tohoto dokumentu pokyny nebo nástroje. Pokud neexistuje, vytvořte ji.

Zásadní změna přidá hodnotu, ale bolesti zákazníka bude příliš vysoká.

Ne všechny typy nezměněných změn se vytvářejí stejně – některé jsou podstatně větší bolestivý, že ostatní jsou založené na našich zkušenostech a na základě zkušeností zákazníků. Například změny rozhraní mohou být bolestivý, ale pokud je zásadní změna jedna, ve které má zákazník pravděpodobně rozšířený/implementovaný v minulosti (například systém diagnostiky vizualizace), skutečné náklady budou pravděpodobně nedostatečné. Pokud je však změnou typ pole v ScriptableObject (například na jednom ze základních profilů MRTK), může to způsobit obrovské bolesti zákazníků. Zákazníci už naklonují výchozí profil, sloučení nebo aktualizace profilů může být mimořádně obtížné (tj. přes textový editor během slučování) a opakované zkopírování výchozího profilu a jeho opětovné konfigurace na základě ruky je extrémně pravděpodobně obtížné ladit regrese.

Tyto změny se musí vrátit do poličky, dokud větev neexistuje, která umožní výrazné zásadní změny (společně s významnou hodnotou, která zákazníkům poskytne důvod k upgradu). Taková větev v tuto chvíli neexistuje. V našich budoucích schůzkách pro plánování iterací si projdeme sadu změn/problémů, které byly příliš rozstupnější, abyste zjistili, zda jsme dosáhli kritického množství změn, které je možné provést v jednom okamžiku. Všimněte si, že se nejedná o nebezpečnou větev, aniž by bylo nutné dělat v důsledku omezených prostředků, které máme k dispozici, a faktu, že budeme muset rozdělit testování a ověřování mezi těmito dvěma. V případě, že existuje, je nutné mít k dispozici jasný a dobře oznámené počáteční a koncové datum takové větve.

Dlouhodobá Správa nejnovějších změn

V dlouhodobém období byste se měli snažit snížit rozsah toho, co je zásadní změna, a to zvýšením sady podmínek v seznamu B. Po přeposílání sady věcí v seznamu A bude vždycky pro sadu souborů a prostředků, které považujeme za "veřejnou plochu rozhraní API", vždy technicky rozlomeno. Způsob, jak můžeme získat trochu větší volnost pro iteraci (tj. Změna interních podrobností implementace, umožnění snazšího refaktoringu a sdílení kódu mezi více třídami atd.) je explicitní explicitní, které části kódu jsou oficiální, spíše než podrobnosti implementace.

Jedna z věcí, které už jsme udělali, je zavedení konceptu "experimentální" funkce (která patří do experimentálního oboru názvů, nemusí mít testy/dokumentaci a veřejně funkční, ale může se odebrat a aktualizovat bez upozornění). Tato skutečnost má za úkol přidat nové funkce dřív, než se dostanete k předchozí zpětné vazbě, ale nepůjde hned přivázat na plochu rozhraní API (vzhledem k tomu, že se nám nedaří plně promyslet plochu rozhraní API).

Další příklady věcí, které mohou v budoucnu pomáhat

  • Použití klíčového slova Internal To umožňuje, aby máme sdílený kód v rámci našich vlastních sestavení (pro snížení duplicit kódu) bez toho, aby bylo možné vytvářet věci jako veřejné pro externí příjemce.
  • Vytvoření oboru názvů "Internal" (tj. Microsoft. MixedReality. Toolkit. Interní. Utilities), kde veřejně zdokumentuje, že cokoli, co je v tomto interním oboru názvů, se může kdykoli změnit a dá se odebrat atd. To se podobá tomu, jak knihovny hlaviček jazyka C++ využívají obory názvů:: Internal pro skrytí podrobností implementace.