Kompatibilitástörő változások

Az MRTK felhasználói egy stabil kiadási API-felületre támaszkodnak, hogy anélkül tudják az MRTK frissítéseit átveszni, hogy minden alkalommal jelentős használszavak.

Ez az oldal az MRTK-ban történt jelentős változásokra vonatkozó jelenlegi szabályzatunkat ismerteti, valamint néhány hosszabb távú céllal ismerteti, hogy hogyan kezelhető a jelentős változások alacsonyan 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ég.

Mi az a friss 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ában 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 vagy nyilvános tagjának vagy funkciójának eltávolítása, frissítése (típus/definíció módosítása, magánjellegűvé 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 a ScriptableObject nyilvános tulajdonságának (különösen a profilok módosításainak) átnevezése.
  • Egy ScriptableObject mező típusának módosítása (különösen a profilok módosítása).
  • Bármely osztály vagy felület névterének vagy asmdefs-ének frissítése.
  • Egy parancsfájl eltávolítása vagy eltávolítása az előfab legfelső szintű objektumán.

B lista

  • A szóban forgó eszköz az alapcsomagban található (vagyis a következő 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 (azaz az MRTK/Examples/mappa egy részében) található összes eszköz bármikor változhat, mivel az olyan eszközöket, amelyek a felhasználók által "referencia-implementációként" másolhatók és megtekinthetők, 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 kísérletiként címkézett funkciókban) található eszközök azok, amelyek a kellő gondosság (tesztek, felhasználói felületi iterációk, dokumentáció) előtt vannak közzétéve, és korábban vannak közzétéve, hogy hamarabb visszajelzést kapnak. Mivel azonban nem rendelkezik tesztekkel és dokumentációval, és mivel valószínűleg nem töröltük 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 lebontó változások felülete nagyon nagy, fontos megjegyezni, hogy egy olyan abszolút s szabály, amely szerint "nincsenek feltöréses változások", előfordulhatnak olyan problémák, amelyek csak a feltörés miatt javíthatóak. Más módon csak úgy lehetünk "nem jelentős változások", ha egyáltalán nincsenek változások.

Á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 mi a helyzet a breaking changes (Mi a helyzet a töredt változásokkal?

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ódszer, a jelenlegi szabályzat az egyes lebontó változások kiértékelése annak érdekében, hogy megértsük, hogy a módosítás előnyei meghaladják-e a fogyasztó számára a változás befogadása által járó költségeket. Arról, hogy mit érdemes tenni, és mi nem, általában a pr-ről vagy a probléma megvitatásról lesz szó.

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

A feltöréses változás értéket ad hozzá, de úgy írható meg, hogy az ne legyen töréken.

Ez a LE-hez például egy olyan ú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 a funkció hosszú távú használhatóságát vagy struktúráját veszélyeztetné.

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

Dokumentálja a használhatatlant hozó változásokat, és adja meg a lehető legjobb megoldásokat (vagyis az áttelepítés részletes lépéseit, vagy még jobb, ha az ügyfél számára automatikusan áttérő eszközökről van szükség). Minden kiadás tartalmazhat néhány jelentős változást, amelyek nem teljesek – ezeket mindig dokumentálni kell a dokumentációban, ahogyan az ebben a pr-ban történt. Ha már létezik a 2.x.x→2.x+1.x+1 migrálási útmutató, akkor 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ának túl magasnak kell lennie

Nem minden típusú változást hozunk létre egyenlően – némelyik lényegesen inkább az, amit mások a tapasztalataink és az ügyfélélmények alapján tapasztalnak. Előfordulhat például, hogy az interfészek módosításai nem teljesek, de ha a használjuk azt a változást, amelyben az ügyfél nem valószínű, hogy a múltban (például a diagnosztikai vizualizációs rendszerben) kiterjesztette/megvalósította volna, 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 az ügyfelek számára nagy problémát okoz. 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 regressziók hibakereséséhez.

Ezeket a módosításokat vissza kell álltatni 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 jelentős" változásokat/problémákat, hogy lássuk, elértük-e a kritikus tömeget, hogy ésszerű legyen egyszerre követni a módosítások egy halmazát. Vegye figyelembe, hogy a "minden engedélyezett" ágat nem kell kellő gondossággal elosztani a rendelkezésre álló korlátozott mérnöki erőforrások miatt, és az, 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, ha létezik.

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

Hosszú távon arra kell törekednünk, hogy a B lista feltételkészletének növelésével lecsökkentsük a fontos változások hatókörét. Az A lista további lépései technikailag mindig a "nyilvános API-felületen" lévőnek ítélt fájl- és adathalmazt fogják feltörni. Az iteráció nagyobb szabadsága (vagyis a belső implementáció részleteinek módosítása, a kód több osztály közötti egyszerűbb újradarabolása és megosztása stb.) kifejezettebb módja annak, hogy a kód mely részei a hivatalos felület, és nem az implementáció részletei.

Már bevezettünk egy "kísérleti" funkciót (amely a kísérleti névtérben található, 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 (mivel 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é teszi, hogy a saját szerelvényeinkben közös kódot is megosztsunk (a kód duplikálásának csökkentése érdekében), anélkül, hogy a dolgokat nyilvánosan elérhetővé tennénk a külső fogyasztók számára.
  • "Belső" névtér (például Microsoft.MixedReality.Toolkit.Internal.Utilities) létrehozása, ahol nyilvánosan dokumentáljuk, hogy a 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.