Önemli bir hatayı giderirken anlamsal sürüm oluşturma

Şu anda çok fazla kamusal kullanımı olan bir kütüphaneyi yönetiyorum ve semantik versiyonlama hakkında bir sorum vardı . Kütüphanenin yanlış uygulanmış ve her zaman yanlış uygulanmış oldukça önemli bir bölümünü yeniden gözden geçirmek istiyorum. Ancak bunu yapmak, büyük bir karar olan genel API'de değişiklikler anlamına gelir.

Yapmak istediğim değişiklik yineleyicilerin nasıl kullanıldığı hakkında. Şu anda, kullanıcılar bunu yapmak zorundadır:

while ($element = $iterator->next()) {
   // ...
}

Bu yanlış, en azından PHP'nin yerel Iterator arabiriminde . Bununla değiştirmek istiyorum:

while ($iterator->valid()) {
   $element = $iterator->current();
   // ...
   $iterator->next();
}

aşağıdakilere benzer:

foreach ($iterator as $element) {
    // ...
}

Eğer semantik sürüm için Tom'un kılavuzunda bakarsak, o açıkça kamu API herhangi bir değişiklik (yani olanlar belirtiyor değil geriye dönük olarak uyumlu), büyük bir tahliyesini haklı gerekir. Kütüphane 1.7.3'ten 2.0.0'a atlayacaktı ki bu benim için çok uzak bir adım. Sadece bir özelliğin düzeltildiğinden bahsediyoruz.

Sonunda 2.0.0 yayımlamayı planlıyorum, ancak kütüphaneyi tamamen yeniden yazdığınızda ve çok sayıda genel API değişikliği uyguladığınızda bunun olduğunu düşündüm . Bu yeniden düzenlemenin tanıtımı büyük bir sürüm sürümü gerektiriyor mu? Gerçekten nasıl olduğunu göremiyorum - 1.8.0 veya 1.7.4 olarak serbest bırakmaktan daha rahat hissediyorum. Kimsenin tavsiyesi var mı?

Tereddüt ediyorsun çünkü anlamsal versiyonlama yapmak istemiyorsun, "reklam destekli versiyonlama" yapmak istiyorsun. "2.0" sürüm numarasının dünyaya, API'nızı değiştirdiğinizi değil, kitaplığınızda bir sürü yeni harika özelliğe sahip olduğunuzu söylemesini beklersiniz. Sorun değil (birçok yazılım şirketi ve / veya geliştirici bunu yapıyor). IMHO aşağıdaki seçeneklere sahiptir:

• anlamsal sürümlemeye sadık kalın ve sürüm numarasını 2.0.0 olarak değiştirmeniz gerektiği gerçeğini yaşayın
• sürüm düzeninizi 4 sayı olarak değiştirin. "1.1.7.3" şu anki sürümünüz, API değiştirildikten sonraki "1.2.0.0" ve "tamamen yeni 2.x ürün ailesinin" ilk sürümü "2.0.0.0"
• düzeltmenizi geriye doğru uyumlu hale getirin (işlevini değiştirmeyin next, yalnızca validve currentişlevlerini ekleyin ). Sonra bir sonraki sürüm numarası olarak "1.8.0" kullanabilirsiniz. Davranışını değiştirmenin nextgerçekten önemli olduğunu düşünüyorsanız , bunu 2.0.0'da yapın.

Tom'un semantik versiyonlama kılavuzuna sadık kalın.

Bir kamu API Herhangi önemli bir değişiklik gerekir iki nokta birini yapılabilir:

1. Asla
2. Büyük bir sürüm güncellemesinde

Bu arada benim oyum birincisi. Ama bunun sadece bir şeyleri önemsemeye uygun olduğunu kabul ediyorum.

Sorun geriye dönük uyumluluğu korumak ve API'nizin önceki kullanıcıları için bir şeyleri kırmamanızı sağlamaktır.

Özünde, değişikliğin farkında olmayan kullanıcılarınız için bir dizin oluşturma hatası oluşturuyorsunuz. Böyle bir değişikliği zorlamak, tüm kullanıcılarınızı aşağıdakileri yapmaya zorlar:

1. Yeni yaklaşımı kullanmak için düzeltmeyi kodlayın
2. Düzeltmeyi doğrulayın ve hiçbir şeyi bozmadığından emin olun
3. Ürünlerinin yeni sürümlerini son kullanıcılarına gönderin

Bu, özellikle bu gibi değişiklikleri doğrulamak için ne kadar az projenin test senaryosu olduğunu düşündüğünüzde çok fazla çaba harcayabilir. Kullanıcılarınızdan, kurulumlarını da güncellemeleri gereken alt kullanıcı sayısını düşündüğünüzde çaba miktarı artar.

Bu kadar küçük bir şey için, gitmesine izin verdim ve onunla uğraşmam.
Eğer gerçekten rahatsız (ki görünüşe göre yapar ya da sen-cekti istemek) o zaman ben aşağıdakileri yapardı.

1. Kod ağacınızda v2.0.0 dalını oluşturun
2. Bu değişiklik olan v2.0.0 şubesine ilk katkıyı yapın
3. Release NotesDeğişikliğin geldiğini yayınlamak için önceden bir önizleme gönderin

Ve sonra sürüm numarasını yeni bir büyük sürüme yükseltmeyi haklı kılan diğer şeyleri biriktirmek biraz zaman alacağından sabırlı olun. Gelişmiş bildirim (bölüm 3), değişikliğin ne kadar etkili olacağını bulmak için son kullanıcılardan geri bildirim almanız için size zaman tanır.

Alternatif bir çözüm, istediğiniz şekilde çalışan yeni bir işlev eklemektir.

Varsa , düzeltmeyi sağlamak için foo()oluşturursunuz fooCorrect(), aynı zamanda geriye dönük uyumluluğu da tamamen korursunuz. Ve bir noktada foo()başkalarının onu kullanmamasını bilmesine izin vermeyebilirsiniz .

Meydan göreceksiniz ki doğası vardır başka bir şey içinde fooCorrect()hangi gerektirmektedir 's güncelleme ve ne kadar son fooCorrectedCorrect()veya başka saçma saçma.

Bunun gerçekten düzeltilmesini istiyorsanız , bu alternatif yaklaşım muhtemelen en iyi yoldur. API'nın çalışmasını zorlaştırdığı için bu şekilde birçok ek işlev oluşturmanın farkında olun ve bu konuda dikkatli olun. Ve bu farkındalık bu tür problemlerin en kötüsünü önlemek için yeterli olabilir.

Ancak bu, küçük bir şeyi düşünmek için "en az kötü" yaklaşım olabilir.