Kompatibilitástörő változások – MRTK2

Az MRTK-felhasználók attól függnek, hogy stabil kiadási API-felülettel rendelkeznek-e, hogy az MRTK frissítéseit anélkül tudják elvégezni, hogy minden alkalommal nagy kompatibilitástörő módosításokat hajtanak végre.

Ez az oldal ismerteti az MRTK kompatibilitástörő változásaira vonatkozó jelenlegi szabályzatunkat, valamint néhány hosszabb távú célt, amelyek célja az, hogy jobban kezelhessük a kompromisszumot a kompatibilitástörő változások alacsonyan tartása és a kód megfelelő hosszú távú technikai módosítása között.

Mi az a kompatibilitástörő változás?

A változás akkor rendkívüli változás, ha megfelel az A listában szereplő feltételek bármelyikének, és megfelel a B listában szereplő összes feltételnek

A listázása

• Bármely felület bármely tagjának vagy funkciójának hozzáadása, eltávolítása vagy frissítése (vagy a teljes felület eltávolítása/átnevezése).
• A védett vagy nyilvános tagok vagy osztályfunkciók eltávolítása, frissítése (típus/definíció módosítása, privát vagy belsővé tétele). (vagy a teljes osztály eltávolítása/átnevezése).
• Az osztály által aktivált események sorrendjének változása.
• Bármely privát szerializált mező átnevezése (a hozzá tartozó FormerlySerializedAs címke nélkül) vagy nyilvános tulajdonság egy ScriptableObjecten (különösen a profilok változásai).
• A SzkriptableObject mezőtípusának módosítása (különösen a profilok módosítása).
• Frissítések bármely osztály vagy felület névterébe vagy asmdefsébe.
• Az előfabok eltávolítása vagy egy szkript eltávolítása az előfab legfelső szintű objektumában.

B lista

• A szóban forgó objektum az alapcsomagban található (azaz az alábbi mappák egyikében található):

  • MRTK/Core
  • MRTK/Szolgáltatók/
  • MRTK/Szolgáltatások/
  • MRTK/SDK/
  • MRTK/bővítmények

• A szóban forgó objektum nem tartozik a kísérleti névtérhez.

Fontos

A példacsomagban (azaz az MRTK/Példák/ mappa egy része) található objektumok bármikor változhatnak, mivel az eszközöket úgy tervezték, hogy azokat a fogyasztók "referencia-implementációkként" másolják és tekinthetik meg, de nem részei az API-k és eszközök alapvető készletének. A kísérleti névtérben lévő eszközök (vagy általában a kísérletiként megjelölt funkciók) azok, amelyek az átvilágítás elvégzése előtt közzé lesznek téve (pl. tesztek, UX iteráció, dokumentáció), és korai közzétételre kerülnek, hogy hamarabb visszajelzést kapjanak. Mivel azonban nincsenek tesztjeik és dokumentációjuk, és mivel valószínűleg nem tették le az összes interakciót és tervet, olyan állapotban tesszük közzé őket, amelyben a nyilvánosságnak azt kell feltételeznie, hogy változhatnak (azaz módosíthatók, teljesen eltávolíthatók stb.).

További információt a Kísérleti funkciók című témakörben talál.

Mivel a törési változások felülete nagyon nagy, fontos megjegyezni, hogy a törés nélküli módosításokat kimondó abszolút szabály lehetetlen lenne – előfordulhatnak olyan problémák, amelyeket csak józanul lehet kijavítani törésmódosítással. Másként fogalmazva, az egyetlen módja annak, hogy valóban "nem törik meg a változásokat" az, hogy egyáltalán nincsenek változások.

Állandó szabályzatunk az, hogy ha lehetséges, ne módosítsunk kompatibilitástörő módosításokat, és csak akkor, ha a változás jelentős ügyfél- vagy keretrendszer-hosszú távú értéket hozna létre.

Teendők a kompatibilitástörő változásokhoz

Ha a funkció hosszú távú szerkezetének és életképességének veszélyeztetése nélkül is el lehet érni valamit, ne végezze el a kompatibilitástörő változást. Ha nincs más megoldás, a jelenlegi szabályzat az egyes törésmódosítások kiértékelése, annak megértése, hogy a módosítás előnyei meghaladják-e a módosítás elnyelésének költségeit a fogyasztó számára. Vita arról, hogy mit érdemes csinálni, és mi nem kerül sor általában a PR vagy kérdés vita magát.

Ami itt történhet, az több gyűjtőbe is beleeshet:

A kompatibilitástörő változás értéket ad, de megírható úgy, hogy ne törje meg

Ez a lekéréses kérelem például hozzáadott egy új funkciót, amely eredetileg kompatibilitástörő módon lett megírva – módosított egy meglévő felületet –, majd újraírta, ahol a funkció saját felületként lett felbontva. Ez általában a lehető legjobb eredmény. Ha így tesz, ne kényszerítse a módosítást nem törhető formába, mert az veszélyeztetné a funkció hosszú távú életképességét vagy szerkezetét.

A kompatibilitástörő változás elegendő értéket ad az ügyfélnek ahhoz, hogy érdemes

Dokumentálja a kompatibilitástörő módosításokat, és nyújtja a lehető legjobb kockázatcsökkentést (azaz a migrálás előíró lépéseit, vagy még jobb eszközhasználatot, amely automatikusan migrálódik az ügyfél számára). Minden kiadás tartalmazhat egy kis mennyiségű, kompatibilitástörő módosítást – ezeket mindig dokumentálni kell a dokumentumokban, ahogyan az ebben a kérelemben történt. Ha már létezik 2.x.x→2.x+1.x+1 áttelepítési útmutató, adjon hozzá utasításokat vagy eszközöket a dokumentumhoz. Ha nem létezik, hozza létre.

A kompatibilitástörő változás értéket ad, de az ügyfél fájdalma túl magas lenne

Nem minden törési változás jön létre egyenrangúként – némelyik sokkal fájdalmasabb, mint mások, a tapasztalataink és az ügyfélélmények alapján. Előfordulhat például, hogy a felületek változásai fájdalmasak, de ha a kompatibilitástörő változás olyan, amelyben az ügyfél nem valószínű, hogy korábban kiterjesztett/implementált (például a diagnosztikai vizualizációs rendszer), akkor a tényleges költségek valószínűleg alacsonyak. Ha azonban a változás egy ScriptableObject mezőtípusa (például az MRTK egyik alapvető profilján), akkor ez nagy ügyfélfájdalmakhoz vezethet. Az ügyfelek már klónozzák az alapértelmezett profilt, a profilok egyesítése/frissítése rendkívül nehéz lehet manuálisan (például egy szövegszerkesztőn keresztül az egyesítés ideje alatt), és az alapértelmezett profil ismételt másolása és minden manuális újrakonfigurálása rendkívül nehéz hibakeresési regressziókhoz vezethet.

Ezeket a módosításokat vissza kell helyeznünk a polcra, amíg létre nem jön egy ág, amely jelentősen megszakítja a módosításokat (a jelentős értékkel együtt, amely okot ad az ügyfeleknek a frissítésre). Egy ilyen ág jelenleg nem létezik. A jövőbeli iterációs tervezési értekezleteken áttekintjük azokat a módosításokat/problémákat, amelyek "túl súlyosak" voltak ahhoz, hogy megállapítsuk, elértünk-e egy kritikus tömeget, hogy ésszerű legyen egyszerre végrehajtani egy sor módosítást. Vegye figyelembe, hogy veszélyes egy "minden engedélyezett" ág létrehozása anélkül, hogy kellő gondossággal járnánk el a rendelkezésre álló korlátozott mérnöki erőforrások, valamint az a tény, hogy a tesztelést és az ellenőrzést fel kell osztanunk a kettő között. Egy ilyen ágnak egyértelmű célokkal és jól kommunikált kezdési és befejezési dátummal kell rendelkeznie, ha létezik.

A kompatibilitástörő változások hosszú távú kezelése

Hosszú távon arra kell törekednünk, hogy csökkentsük a B lista feltételkészletének növelésével a rendkívüli változás hatókörét. Az A lista elemeinek továbbhaladása technikailag mindig feltöri azokat a fájlokat és eszközöket, amelyeket a "nyilvános API-felületen" tekintünk. Az iterációhoz (azaz a belső implementáció részleteinek módosításával, a kód több osztály közötti könnyebb újrabontásához és megosztásához stb.) az a mód, hogy pontosabban fogalmazzuk meg, hogy a kód mely részei a hivatalos felület, nem pedig a megvalósítás részletei.

Egy dolgot már megtettünk, hogy bevezetjük a "kísérleti" funkció fogalmát (a kísérleti névtérbe tartozik, lehet, hogy nem rendelkezik tesztekkel/dokumentációval, és nyilvánosan létezőnek nyilvánítják, de figyelmeztetés nélkül eltávolíthatók és frissíthetők). Ez lehetővé tette, hogy hamarabb új funkciókat adjon hozzá, hogy korábbi visszajelzéseket kapjon, de ne legyen azonnal az API felületéhez kötve (mert lehet, hogy nem teljesen átgondoltuk az API-felületet).

Egyéb példák olyan dolgokra, amelyek segíthetnek a jövőben

• A belső kulcsszó használata. Ez lehetővé tenné számunkra, hogy közös kódot használjunk a saját szerelvényeken belül (a kód duplikációjának csökkentése érdekében), anélkül, hogy a dolgokat nyilvánossá tennénk a külső fogyasztók számára.
• Egy "belső" névtér létrehozása (pl. Microsoft.MixedReality.Toolkit.Internal.Utilities), ahol nyilvánosan dokumentáljuk, hogy a belső névtérben található összes adat bármikor változhat, és eltávolítható stb. Ez hasonló ahhoz, ahogyan a C++ fejléctárak a ::belső névterek használatával elrejtik az implementáció részleteit.