Kompatibilitástörő változások

Az MRTK felhasználói egy stabil kiadási API-felülettől függenek, így anélkül tudják az MRTK frissítéseit átveszni, hogy minden alkalommal jelentős változásokat kell elenyészni.

Ez az oldal bemutatja az MRTK-beli legfrissebb változásokra vonatkozó jelenlegi szabályzatunkat, valamint néhány hosszabb távú célokat azzal kapcsolatban, hogy hogyan kezelhetők jobban a jelentős változások alacsony szinten tartása és a kód megfelelő hosszú távú műszaki módosításainak megvalósításához szükséges különbségek.

Mi az a feltörést nem megváltoztató változás?

A változás akkor vált feltörést, ha az megfelel az A lista bármely feltételének, ÉS megfelel a B listán található összes feltételnek

A lista

  • Bármely felület bármely tagját vagy funkcióját (vagy a teljes felület eltávolítását/átnevezését/átnevezését) összeadása, eltávolítása vagy frissítése.
  • Az osztály védett, nyilvános tagjának vagy funkciójának eltávolítása, frissítése (típusának/definíciójának módosítása, priváttá vagy belsővé váltása). (vagy a teljes osztály eltávolítása/átnevezése).
  • Az osztály által elbocsátott események sorrendjének módosítása.
  • Bármely privát szerializált mező átnevezése (megfelelő FormerlySerializedAs címke nélkül) vagy nyilvános tulajdonság átnevezése egy ScriptableObjecten (különösen a profilok módosításai).
  • Egy ScriptableObject mező típusának módosítása (különösen a profilok változásai).
  • Bármely osztály vagy felület névterének vagy asmdefs-ének frissítése.
  • Az előfab legfelső szintű objektumán lévő parancsfájlok előzetes vagy eltávolítása.

B lista

  • A szóban forgó eszköz az alapcsomagban található (vagyis az alábbi mappák egyikében található):

    • MRTK/Core
    • MRTK/Szolgáltatók/
    • MRTK/Services/
    • MRTK/SDK/
    • MRTK/bővítmények
  • A szóban forgó eszköz nem tartozik a kísérleti névtérhez.

Fontos

A példacsomagban (vagyis az MRTK/Examples/mappában) található összes eszköz bármikor változhat, mivel az olyan eszközök, amelyek másolására és megtekintésére a fogyasztók "referencia-implementációként" vannak kialakítva, de nem részei az API-k és eszközök alapvető készletének. A kísérleti névtérben (vagy általánosabban a kísérletiként megjelölt funkciók) olyan eszközök, amelyek minden kellő gondosság előtt közzé vannaktéve (tesztek, felhasználói felület iterációja, dokumentáció), és a korai közzétételük a visszajelzések korai szakaszában történik. Mivel azonban nem rendelkezik tesztekkel és dokumentációval, és mivel valószínűleg nem oltottuk le az összes interakciót és kialakítást, olyan állapotban közzétenjük őket, amelyben a nyilvánosságnak azt kell feltételeznie, hogy ezek változhatnak (azaz módosíthatók, teljesen eltávolíthatók stb.).

További információ: Kísérleti funkciók.

Mivel a feltörést el nem hozó változások felülete nagyon nagy, fontos megjegyezni, hogy egy olyan abszolút szabály, amely szerint a "nem számító változás" lehetetlen lenne – előfordulhatnak olyan problémák, amelyek csak a feltöréses változással javíthatóak. Más szóval csak úgy lehetünk "nem jelentős változások", ha egyáltalán nem lesz változás.

Az állandó szabályzatunk az, hogy ha lehetséges, elkerüljük a feltörést, és csak akkor tegye ezt, ha a változás jelentős ügyfél- vagy keretrendszerbeli hosszú távú értéket hozna létre.

Mi a helyzet a breaking changes (Mi a helyzet a breaking changes? (Mi a mi a helyzet

Ha a funkció hosszú távú struktúrájának és működőképességének veszélyeztetése nélkül is el lehet érni valamit, akkor ne módosítsa a változást. Ha nincs más mód, a jelenlegi szabályzat az egyes lebontó változások kiértékelése annak érdekében, hogy meg tudja érteni, hogy a módosítás előnyei meghaladják-e a fogyasztót a változás befogadása költségeket. Általában a pr-ről vagy a probléma megvitatásán kell vitatni, hogy mit érdemes tenni, és mi nem.

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

A feltörést el nem érő változás értéket ad, de úgy írható meg, hogy az ne legyen törékeny.

Ez a LE-hez például egy új funkció lett hozzáadva, amely eredetileg hibásan lett megírva – módosított egy meglévő felületet –, de aztán átírták, ahol a funkció a saját felületére lett bontva. Általában ez a legjobb eredmény. Ne kényszerítsen egy változtatást nem feltörő formába, ha ez veszélyeztetné a funkció hosszú távú használhatóságát vagy szerkezetét.

A feltöréses változás elegendő értéket ad az ügyfélnek, amit érdemes tenni

Dokumentálja a használhatatlanhatatlanság változásait, és adja meg a lehető legjobb megoldásokat (vagyis az áttelepítés részletes lépéseit, vagy még jobb, az ügyfél számára automatikusan áttérő eszközök használatát). Minden kiadás tartalmazhat kis mennyiségű, nem megfelelő módosítást – ezeket mindig dokumentálni kell a dokumentációban, ahogyan a lekért lekért dokumentumban is tette. Ha már létezik a 2.x.x→2.x+1.x+1 áttelepítési útmutató, adjon hozzá utasításokat vagy eszközt a dokumentumhoz. Ha még nem létezik, hozza létre.

A feltöréses változás értéket ad, de az ügyfél fájdalmát túl magas lenne

Nem minden típusú feltörést hozunk létre egyenlően – vannak, amelyek a tapasztalataink és az ügyfélélmények alapján lényegesen inkább le vannak törve. Előfordulhat például, hogy az interfészek módosítása nem túl nagy, de ha a használva változást nem valószínű, hogy az ügyfél a múltban kiterjesztette/megvalósította (például a diagnosztikai vizualizációs rendszer), akkor a tényleges költség valószínűleg nem lesz semmi. Ha azonban a módosítás a ScriptableObject egyik mezőjének típusa (például az MRTK egyik alapvető profilján), az nagy valószínűséggel komoly felhasználói problémákat okozhat. Az ügyfelek már klónoztá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ővel az egyesítés során), és az alapértelmezett profil újbóli másolása és minden manuális újrakonfigurálása rendkívül nagy valószínűséggel vezet a hibakeresési regressziókhoz.

Ezeket a módosításokat vissza kell tenünk a polcra, amíg meg nem létezik egy ág, amely jelentős változásokat tesz lehetővé (a jelentős értékkel együtt, amely okot ad az ügyfeleknek a frissítésre). Ilyen ág jelenleg nem létezik. A jövőbeli iteráció-tervezési értekezleteinken áttekintjük a "túl kritikus" változásokat/problémákat, hogy lássuk, elértük-e a kritikus tömeget, hogy ésszerű legyen egyszerre egy sor módosítást követni. Vegye figyelembe, hogy veszélyes lehet egy "minden engedélyezett" ágat a kellő gondosság nélkül elforgatni a rendelkezésre álló mérnöki erőforrások miatt, valamint az a tény, hogy a tesztelést és az ellenőrzést el kell különítenünk a két ág között. Az ilyen ágaknak egyértelmű céllal és jól kommunikált kezdő és záró dátummal kell kezdődni, amikor létezik.

A lebontó változások hosszú távú kezelése

Hosszú távon a B lista feltételkészletének növelésével le kell szűkülnünk a feltörést jelentő változások hatókörét. Az A lista további lépései technikailag mindig használva lesznek a "nyilvános API-felületen" lévőnek ítélt fájlok és eszközök. Az iteráció nagyobb szabadsága (vagyis a belső megvalósítási részletek módosítása, a kód több osztály közötti egyszerűbb újradarabolása és megosztása stb.) explicitebb módja annak, hogy a kód mely részei a hivatalos felület, és nem az implementáció részletei.

Eddig bemutattunk egy "kísérleti" funkciót (amely a kísérleti névtérhez tartozik, nem biztos, hogy rendelkezik tesztekkel/dokumentációval, és nyilvánosan le van oltva, de figyelmeztetés nélkül eltávolítható és frissíthető). Ez lehetővé teszi, hogy hamarabb adjon hozzá új funkciókat a korábbi visszajelzések le szolgáltatásához, de ne legyen azonnal az API felülethez kötve (mert előfordulhat, hogy még nem teljesen átgondolta az API felületét).

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

  • A belső kulcsszó használata. Ez lehetővé tenné, hogy a saját szerelvényeinkben közös kódot (a kód duplikálásának csökkentése érdekében) a külső fogyasztók számára való nyilvánosság nélkül is megosztanunk kellene.
  • "Belső" névtér létrehozása (például Microsoft.MixedReality.Toolkit.Internal.Utilities), ahol nyilvánosan dokumentáljuk, hogy az adott belső névtéren belül található minden elem bármikor változhat, és eltávolítható stb. Ez hasonló ahhoz, ahogy a C++ fejléctárak a ::internal névtereket használják az implementáció részleteinek elrejtéséhez.