Bagikan melalui

Perubahan mencolok — MRTK2

  • Artikel

Konsumen MRTK bergantung pada memiliki permukaan API rilis-ke-rilis yang stabil, sehingga mereka dapat mengambil pembaruan untuk MRTK tanpa memiliki perubahan besar yang melanggar setiap kali.

Halaman ini menjelaskan kebijakan kami saat ini mengenai melanggar perubahan dalam MRTK, bersama dengan beberapa tujuan jangka panjang tentang bagaimana kami dapat mengelola tradeoff dengan lebih baik antara menjaga perubahan yang melanggar tetap rendah dan dapat membuat perubahan teknis jangka panjang yang tepat pada kode.

Apa itu perubahan yang melanggar?

Perubahan adalah perubahan yang melanggar jika memenuhi salah satu kondisi dalam Daftar A DAN memenuhi semua kondisi dalam daftar B

Daftar A

  • Penambahan, penghapusan, atau pembaruan anggota atau fungsi antarmuka apa pun (atau penghapusan/penggantian nama seluruh antarmuka).
  • Penghapusan, pembaruan (mengubah jenis/definisi, membuat privat atau internal) dari anggota atau fungsi kelas yang dilindungi atau publik. (atau menghapus/mengganti nama seluruh kelas).
  • Perubahan urutan peristiwa yang dipicu oleh kelas.
  • Penggantian nama SerializedField privat apa pun (tanpa tag FormerlySerializedAs) atau properti publik yang sesuai pada ScriptableObject (terutama perubahan pada profil).
  • Mengubah jenis bidang pada ScriptableObject (terutama perubahan pada profil).
  • Updates ke namespace layanan atau asmdef dari kelas atau antarmuka apa pun.
  • Penghapusan prefab atau penghapusan skrip pada objek tingkat atas prefab.

Daftar B

  • Aset yang dimaksud ada dalam paket fondasi (yaitu di salah satu folder berikut):

    • MRTK/Core
    • MRTK/Penyedia/
    • MRTK/Services/
    • MRTK/SDK/
    • MRTK/Extensions

  • Aset yang dimaksud bukan milik namespace eksperimental.

Penting

Setiap aset yang berada dalam paket contoh (yaitu bagian dari FOLDER MRTK/Contoh/) dapat berubah kapan saja, karena aset di sana dirancang untuk disalin dan dilihat oleh konsumen sebagai 'implementasi referensi' tetapi bukan bagian dari set inti API dan aset. Aset di namespace eksperimental (atau lebih umum, fitur yang dilabeli sebagai eksperimental) adalah yang diterbitkan sebelum semua uji tuntas telah dilakukan (yaitu pengujian, iterasi UX, dokumentasi) dan diterbitkan lebih awal untuk mendapatkan umpan balik lebih cepat. Namun, karena mereka tidak memiliki pengujian dan dokumentasi, dan karena kami mungkin belum memaku semua interaksi dan desain, kami menerbitkannya dalam keadaan di mana publik harus berasumsi bahwa mereka dapat dan akan berubah (yaitu dimodifikasi, dihapus sepenuhnya, dll).

Lihat Fitur eksperimental untuk informasi selengkapnya.

Karena area permukaan untuk melanggar perubahan sangat besar, penting untuk dicatat bahwa memiliki aturan absolut yang mengatakan "tidak ada perubahan yang melanggar" tidak akan mungkin - mungkin ada masalah yang hanya dapat diperbaiki dengan cara yang waras dengan memiliki perubahan yang melanggar. Untuk menempatkan cara lain, satu-satunya cara kita benar-benar bisa memiliki "tidak ada perubahan yang melanggar" adalah dengan tidak memiliki perubahan sama sekali.

Kebijakan berdiri kami adalah menghindari membuat perubahan yang melanggar jika memungkinkan, dan hanya melakukannya jika perubahan akan mengumpulkan nilai jangka panjang pelanggan atau kerangka kerja yang signifikan.

Apa yang harus dilakukan tentang melanggar perubahan

Jika memungkinkan untuk mencapai sesuatu tanpa perubahan yang melanggar dan tanpa mengorbankan struktur jangka panjang dan kelayakan fitur, jangan lakukan perubahan yang melanggar. Jika tidak ada cara lain, kebijakan saat ini adalah mengevaluasi setiap individu melanggar perubahan, untuk memahami apakah manfaat dari mengambil perubahan melebihi biaya kepada konsumen untuk menyerap perubahan. Perdebatan tentang apa yang layak dilakukan dan apa yang umumnya tidak akan terjadi pada PR atau diskusi masalah itu sendiri.

Apa yang dapat terjadi di sini jatuh ke dalam beberapa wadah:

Perubahan yang melanggar menambah nilai tetapi dapat ditulis dengan cara yang tidak melanggar

Misalnya, PR ini menambahkan fitur baru yang awalnya ditulis dengan cara yang melanggar - ia memodifikasi antarmuka yang ada - tetapi kemudian ditulis ulang di mana fitur tersebut dipecah sebagai antarmukanya sendiri. Ini umumnya hasil terbaik. Jangan mencoba memaksa perubahan menjadi bentuk yang tidak melanggar jika melakukannya akan membahayakan kelayakan jangka panjang atau struktur fitur.

Perubahan yang melanggar menambah nilai yang memadai kepada pelanggan yang layak dilakukan

Dokumentasikan apa perubahan yang melanggar dan berikan mitigasi terbaik (yaitu langkah-langkah preskriptif tentang cara bermigrasi, atau alat yang lebih baik lagi yang akan secara otomatis bermigrasi untuk pelanggan). Setiap rilis mungkin berisi sejumlah kecil perubahan yang melanggar - ini harus selalu didokumentasikan dalam dokumen seperti yang dilakukan dalam PR ini. Jika sudah ada panduan migrasi 2.x.x→2.x+1.x+1, tambahkan instruksi atau alat ke dokumen tersebut. Jika tidak ada, buatlah.

Perubahan yang melanggar menambah nilai tetapi rasa sakit pelanggan akan terlalu tinggi

Tidak semua jenis perubahan yang melanggar dibuat sama - beberapa secara signifikan lebih menyakitkan yang lain, berdasarkan pengalaman kami dan berdasarkan pengalaman pelanggan. Misalnya, perubahan pada antarmuka mungkin menyakitkan, tetapi jika perubahan yang melanggar adalah salah satu di mana pelanggan tidak mungkin telah diperpanjang/diimplementasikan di masa lalu (sistem visualisasi diagnostik, misalnya), maka biaya aktual mungkin rendah hingga apa-apa. Namun, jika perubahan adalah jenis bidang pada ScriptableObject (misalnya, pada salah satu profil inti MRTK), ini kemungkinan akan menyebabkan rasa sakit pelanggan yang besar. Pelanggan telah mengkloning profil default, menggabungkan/memperbarui profil bisa sangat sulit dilakukan secara manual (yaitu melalui editor teks selama waktu penggabungan), dan menyalin ulang profil default dan mengonfigurasi ulang semuanya dengan tangan sangat mungkin menyebabkan sulit untuk men-debug regresi.

Perubahan ini kita harus menempatkan kembali ke rak sampai cabang ada yang akan memungkinkan perubahan yang melanggar secara signifikan (bersama dengan nilai signifikan yang akan memberi pelanggan alasan untuk meningkatkan). Cabang seperti itu saat ini tidak ada. Dalam rapat perencanaan iterasi kami di masa depan, kami akan meninjau serangkaian perubahan/masalah yang 'terlalu melanggar' untuk melihat apakah kami mencapai massa penting untuk membuatnya masuk akal untuk mengejar serangkaian perubahan sekaligus. Perhatikan bahwa sangat berbahaya untuk memutar cabang "semuanya diizinkan" tanpa uji tanggap dilakukan karena sumber daya rekayasa terbatas yang kita miliki, dan fakta bahwa kita harus membagi pengujian dan validasi di kedua cabang tersebut. Perlu ada tujuan yang jelas dan tanggal mulai dan akhir yang dikomunikasikan dengan baik dari cabang tersebut ketika ada.

Manajemen jangka panjang perubahan yang melanggar

Dalam jangka panjang, kita harus berusaha untuk mengurangi cakupan apa yang merupakan perubahan yang melanggar dengan meningkatkan serangkaian kondisi dalam Daftar B. Ke depan set hal-hal dalam Daftar A akan selalu secara teknis melanggar set file dan aset yang kami anggap berada di "permukaan API publik." Cara kita bisa mendapatkan sedikit lebih banyak kebebasan untuk iterasi (yaitu mengubah detail implementasi internal, memungkinkan pemfaktoran ulang dan berbagi kode yang lebih mudah antara beberapa kelas, dll) adalah menjadi lebih eksplisit tentang bagian kode mana yang merupakan permukaan resmi, daripada detail implementasi.

Satu hal yang telah kami lakukan adalah memperkenalkan konsep fitur "eksperimental" (milik dalam namespace eksperimental, mungkin tidak memiliki pengujian/dokumentasi, dan secara publik dinyatakan ada tetapi dapat dihapus dan diperbarui tanpa peringatan). Ini telah memberikan kebebasan untuk menambahkan fitur baru lebih cepat untuk mendapatkan umpan balik sebelumnya, tetapi tidak segera terikat dengan permukaan API-nya (karena kami mungkin belum sepenuhnya memikirkan permukaan API).

Contoh lain dari hal-hal yang dapat membantu di masa depan

  • Penggunaan kata kunci internal. Ini akan memungkinkan kami untuk berbagi kode dalam rakitan kami sendiri (untuk mengurangi duplikasi kode) tanpa membuat hal-hal publik untuk konsumen eksternal.
  • Pembuatan namespace layanan "internal" (yaitu Microsoft.MixedReality.Toolkit.Internal.Utilities), di mana kami secara publik mendokumentasikan bahwa apa pun yang terkandung dalam namespace internal tersebut dapat berubah kapan saja dan dapat dihapus, dll. Ini mirip dengan bagaimana pustaka header C++ akan menggunakan ::namespace internal untuk menyembunyikan detail implementasinya.