Hataya neden olan değişiklikler — MRTK2

  • Makale

MRTK tüketicileri, her seferinde büyük hataya neden olan değişiklikler yapmadan MRTK güncelleştirmelerini alabilmeleri için kararlı bir yayından yayına API yüzeyine sahip olmalarına bağlıdır.

Bu sayfada, MRTK'deki hataya neden olan değişikliklerle ilgili geçerli politikamızın yanı sıra, hataya neden olan değişiklikleri düşük tutma ile kodda doğru uzun vadeli teknik değişiklikleri yapabilme arasındaki dengeyi nasıl daha iyi yönetebileceğimizle ilgili bazı uzun vadeli hedeflerimiz açıklanmaktadır.

Hataya neden olan değişiklik nedir?

Değişiklik, A Listesi'ndeki koşullardan herhangi birini karşılarsa ve B listesindeki tüm koşulları karşılarsa hataya neden olan bir değişikliktir

Liste A

  • Herhangi bir arabirimin üyesinin veya işlevinin eklenmesi, kaldırılması veya güncelleştirililmesi (veya arabirimin tamamının kaldırılması/yeniden adlandırılması).
  • Herhangi bir korumalı veya genel üye veya sınıfın işlevini kaldırma, güncelleştirme (türü/tanımı değiştirme, özel veya iç öğe yapma). (veya sınıfın tamamını kaldırma/yeniden adlandırma).
  • Sınıf tarafından tetiklenen olayların sırasına göre değişiklik.
  • ScriptableObject'te (özellikle profillerde yapılan değişiklikler) herhangi bir özel SerializedField'in (karşılık gelen Bir FormerlySerializedAs etiketi olmadan) veya ortak özelliğinin yeniden adı.
  • ScriptableObject üzerindeki bir alanın türünü değiştirme (özellikle profillerde yapılan değişiklikler).
  • Herhangi bir sınıfın veya arabirimin ad alanına veya asmdefs'sine Güncelleştirmeler.
  • Prefabriklerin kaldırılması veya bir ön satırın en üst düzey nesnesinde betiğin kaldırılması.

Liste B

  • Söz konusu varlık temel pakettedir (örneğin, aşağıdaki klasörlerden birindedir):

    • MRTK/Core
    • MRTK/Sağlayıcılar/
    • MRTK/Hizmetler/
    • MRTK/SDK/
    • MRTK/Uzantılar

  • Söz konusu varlık deneysel ad alanına ait değil.

Önemli

Örnekler paketinde (MRTK/Examples/ klasörünün bir parçası) bulunan varlıklar, tüketiciler tarafından 'başvuru uygulamaları' olarak kopyalanacak ve görüntülenecek şekilde tasarlandığından ancak temel API'lerin ve varlıkların bir parçası olmadığından, herhangi bir zamanda değiştirilebilir. Deneysel ad alanı içindeki varlıklar (veya daha genel olarak deneysel olarak etiketlenmiş özellikler), tüm durum tespiti yapılmadan önce yayımlanan varlıklardır (testler, UX yinelemesi, belgeler) ve geri bildirim almak için erken yayımlanır. Bununla birlikte, testleri ve belgeleri olmadığından ve büyük olasılıkla tüm etkileşimleri ve tasarımları yakalamadığımız için, bunları, kamunun değiştirebileceklerini ve değiştirebileceklerini varsayması gereken bir durumda yayımlarız (örneğin, değiştirilmeli, tamamen kaldırılmalıdır vb.).

Daha fazla bilgi için bkz . Deneysel özellikler .

Hataya neden olan değişikliklerin yüzey alanı çok büyük olduğundan, "hataya neden olan değişiklikler yok" diyen mutlak bir kurala sahip olmanın imkansız olacağını unutmayın; yalnızca hataya neden olan bir değişiklikle aklı başında bir şekilde düzeltilebilen sorunlar olabilir. Başka bir şekilde ifade etmek gerekirse, "hataya neden olan değişiklikler yok" dediğimiz tek yol hiçbir değişiklik olmamasıdır.

Mevcut ilkemiz mümkünse hataya neden olan değişiklikler yapmaktan kaçınmak ve bunu yalnızca değişiklik önemli bir müşteri veya çerçeve uzun vadeli değeri tahakkuk ettirecekse yapmaktır.

Hataya neden olan değişiklikler hakkında yapılması gerekenler

Bir şeyi hataya neden olmadan ve özelliğin uzun vadeli yapısından ve uygulanabilirliğinden ödün vermeden gerçekleştirmek mümkünse, hataya neden olan değişikliği yapmayın. Başka bir yol yoksa, geçerli ilke her bir hataya neden olan değişikliği değerlendirmek ve değişikliği almanın avantajının, değişikliğin tüketiciye maliyetin ağır basıp ağır basmadığını anlamaktır. Ne yapmaya değer ve nelerin ne olmadığıyla ilgili tartışmalar genellikle çekme isteği veya sorun tartışmasının kendisinde gerçekleşir.

Burada olabilecekler birkaç demette yer alır:

Hataya neden olan değişiklik değer ekler ancak hataya neden olmayan bir şekilde yazılabilir

Örneğin , bu ÇEKME isteği başlangıçta bozuk bir şekilde yazılmış yeni bir özellik ekledi. Mevcut bir arabirimi değiştirdi ancak daha sonra özelliğin kendi arabirimi olarak ayrıldığı yerde yeniden yazıldı. Bu genellikle mümkün olan en iyi sonuç olur. Bunu yapmak özelliğin uzun vadeli kullanılabilirliğini veya yapısını tehlikeye atacaksa, bir değişikliği hataya neden olmayan bir forma zorlamaya çalışmayın.

Hataya neden olan değişiklik, müşteriye bunu yapmaya değecek kadar değer katıyor

Hataya neden olan değişikliklerin ne olduğunu belgeleyin ve mümkün olan en iyi azaltmayı (örneğin, nasıl geçirileceğiyle ilgili açıklayıcı adımlar veya müşteri için otomatik olarak geçirilecek daha iyi araçlar) sağlayın. Her sürümde hataya neden olan az miktarda değişiklik olabilir. Bunlar her zaman bu çekme isteğinde olduğu gibi belgelenmelidir. 2.x.x→2.x+1.x+1 geçiş kılavuzu zaten varsa, bu belge için yönergeler veya araçlar ekleyin. Yoksa oluşturun.

Hataya neden olan değişiklik değer katıyor ancak müşteri sıkıntısı çok yüksek olabilir

Tüm hataya neden olan değişiklikler eşit olarak oluşturulmaz; bazıları bizim deneyimimize ve müşteri deneyimlerine dayalı olarak diğerlerinin daha acı verici olmasıdır. Örneğin, arabirimlerdeki değişiklikler acı verici olabilir, ancak hataya neden olan değişiklik müşterinin geçmişte genişletilmiş/uygulanmış olma olasılığının düşük olduğu bir değişiklikse (örneğin, tanılama görselleştirme sistemi), gerçek maliyet büyük olasılıkla hiçe kadar düşüktür. Ancak, değişiklik ScriptableObject üzerindeki bir alanın türüyse (örneğin, MRTK'nın temel profillerinden birinde), bu durum büyük olasılıkla büyük müşteri sorunlarına neden olabilir. Müşteriler varsayılan profili zaten kopyalamış durumdadır; profilleri birleştirmek/güncelleştirmek el ile yapmak son derece zor olabilir (örneğin, birleştirme sırasında bir metin düzenleyicisi aracılığıyla) ve varsayılan profili yeniden kopyalayıp her şeyi el ile yeniden yapılandırmak, hata ayıklamanın zor olmasına neden olabilir.

Bu değişiklikler, önemli ölçüde hataya neden olacak değişikliklere (müşterilere yükseltme nedeni sağlayacak önemli bir değerle birlikte) olanak sağlayacak bir dal var olana kadar rafa geri koymamız gerekir. Böyle bir dal şu anda yok. Gelecekteki yineleme planlama toplantılarımızda, bir dizi değişikliği aynı anda sürdürmeyi makul hale getirmek için kritik bir kitleye ulaşıp ulaşmadığımıza bakmak için 'çok hata veren' değişiklikler/sorunlar kümesini gözden geçireceğiz. Sahip olduğumuz sınırlı mühendislik kaynakları ve test ve doğrulamayı bu ikisi arasında bölmemiz gerekmesi nedeniyle durum tespiti yapılmadan bir "her şeye izin verilir" dalı oluşturmanın tehlikeli olduğunu unutmayın. Böyle bir dal mevcut olduğunda açık bir amaç ve iyi iletişim kuran bir başlangıç ve bitiş tarihi olmalıdır.

Hataya neden olan değişikliklerin uzun vadeli yönetimi

Uzun vadede, B Listesi'ndeki koşullar kümesini artırarak hataya neden olan değişikliğin kapsamını azaltmaya çalışmamız gerekir. A Listesi'ndeki bir dizi öğe her zaman teknik olarak "genel API yüzeyinde" olduğunu kabul ettiğimiz dosya ve varlık kümesi için hataya neden olur. Yineleme için biraz daha fazla özgürlük elde edebilmenin yolu (iç uygulama ayrıntılarının değiştirilmesi, birden çok sınıf arasında kodun daha kolay yeniden düzenlenmesine ve paylaşılmasına olanak sağlama), kodun hangi bölümlerinin resmi yüzey olduğu konusunda uygulama ayrıntıları yerine daha açık olmaktır.

Daha önce yaptığımız bir şey , "deneysel" özellik kavramını tanıtmaktır (deneysel ad alanına aittir, testleri/belgeleri olmayabilir ve herkese açık olarak var olduğu ilan edilir, ancak uyarı olmadan kaldırılabilir ve güncelleştirilebilir). Bu, daha erken geri bildirim almak için yeni özellikleri daha erken ekleme özgürlüğüne sahiptir, ancak API yüzeyine hemen bağlı değildir (ÇÜNKÜ API yüzeyini tam olarak düşünmemiş olabiliriz).

Gelecekte yardımcı olabilecek diğer örnekler

  • İç anahtar sözcüğün kullanımı. Bu, öğeleri dış tüketicilere açık hale getirmeden kendi derlemelerimizde (kod yinelemeyi azaltmak için) paylaşılan koda sahip olmamızı sağlar.
  • İç ad alanı içinde yer alan her şeyin her zaman değiştirilebileceğini ve kaldırılabileceğini herkese açık olarak belgelediğimiz bir "iç" ad alanı (örneğin, Microsoft.MixedReality.Toolkit.Internal.Utilities) oluşturma. Bu, C++ üst bilgi kitaplıklarının uygulama ayrıntılarını gizlemek için ::internal ad alanlarını kullanmasına benzer.