Bazel'da zarar veren değişiklikler yapmamız kaçınılmaz. Tasarımlarımızı değiştirmemiz ve iyi sonuç vermeyenleri düzeltmemiz gerekecek. Ancak, topluluğun ve Bazel ekosisteminin sizi takip ettiğinden emin olmamız gerekiyor. Bu nedenle Bazel projesi geriye dönük uyumluluk politikası benimsedi. Bu belgede, Bazel'ın katkıda bulunanların Bazel'da bu politikaya uygun bir değişiklik yapma süreci açıklanmaktadır.
Doküman tasarımı politikasını uygulayın.
GitHub sorunu
Bazel deposunda GitHub sorunu bildirin. Örneğe bakın.
Önerilerimiz:
Başlık işaretin adıyla başlar (bayrak adı
incompatible_
ile başlar).incompatible-change
etiketini ekleyin.Açıklama, değişikliğin açıklamasını ve ilgili tasarım dokümanlarının bağlantısını içerir.
Açıklamada, kullanıcılara kodlarını nasıl güncellemeleri gerektiğini açıklayan bir taşıma tarifi bulunuyor. İdeal olarak, değişiklik mekanik olduğunda bir taşıma aracı bağlantısı içermelidir.
Açıklamada, kullanıcılar taşımazsa hata mesajı alacakları bir örnek yer alıyor. Böylece GitHub sorunu arama motorlarından daha kolay bulunabilir. Hata mesajının faydalı ve uygulanabilir olduğundan emin olun. Mümkün olduğunda hata mesajında uyumsuz işaretin adı yer almalıdır.
Taşıma aracı için Builderator'a katkıda bulunabilirsiniz.
BUILD
, WORKSPACE
ve .bzl
dosyalarına otomatik düzeltmeleri uygulayabilir.
Ayrıca uyarılar da bildirebilir.
Uygulama
Bazel'da yeni bir bayrak oluşturun. Varsayılan değer yanlış olmalıdır. Yardım metni, GitHub sorununun URL'sini içermelidir. İşaret adı incompatible_
ile başladığından, meta veri etiketlerine ihtiyaç duyar:
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
Kayıt açıklamasına, işaretin kısa bir özetini ekleyin.
Ayrıca RELNOTES:
formunu şu forma ekleyin:
RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
Taahhüt ayrıca ilgili dokümanları da güncellemelidir. Böylece kodun dokümanlarla tutarsız olduğu taahhütler gösterilmez. Dokümanlarımızın sürümü değiştirildiği için dokümanlarda yapılan değişiklikler zamanından önce yayımlanmaz.
Etiketler
Taahhüt birleştirildikten ve uyumsuz değişiklik kullanılmaya hazır olduğunda GitHub sorununa migration-ready
etiketini ekleyin.
Bayrakla ilgili bir sorun bulunursa ve kullanıcıların henüz taşınması beklenmiyorsa:
migration-ready
işaretlerini kaldırın.
Sıradaki ana sürümde işareti değiştirmeyi planlıyorsanız soruna `break-change-X.0" etiketini ekleyin.
Kod depolarını güncelleme
Bazel CI Bazel@HEAD + Downstream sayfasında önemli projelerin listesini test eder. Bunların çoğu genellikle diğer Bazel projelerinin bağımlılarıdır. Bu nedenle, daha geniş bir kitleye yönelik taşımanın engellemesini kaldırmak için bu projelerin taşınması önemlidir. Bu projelerin taşıma durumunu izlemek için bazelisk-plus-incompatible-flags
ardışık düzenini kullanabilirsiniz.
Bu ardışık düzenin nasıl çalıştığını buradan kontrol edebilirsiniz.
Geliştirici destek ekibimiz migration-ready
etiketini izler. Bu etiketi GitHub sorununa eklediğinizde, şunlarla ilgili işlem yapılacaktır:
Taşınması gereken başarısız işlemler ve aşağı akış projelerinin listesini izlemek için GitHub sorununda bir yorum oluşturun (örneğe bakın)
Uyumsuz değişiklik nedeniyle bozulan her aşağı akış projesini sahiplerine bildirmek için GitHub sorunlarını gönderin (örneği inceleyin)
Tüm sorunların hedef sürüm tarihinden önce ele alındığından emin olmak için takip edin
Aşağı akış hattındaki projelerin taşınması, uyumsuz değişiklik yazarının sorumluluğu DEĞİLDİR. Ancak, taşıma işlemini hızlandırmak ve Bazel kullanıcılarının ve Bazel Green Ekibi'nin hayatını kolaylaştırmak için aşağıdakileri yapabilirsiniz.
Satışa dönük projeleri düzeltmek için halkla ilişkiler çalışmaları gönderin.
Taşıma ile ilgili yardım için Bazel topluluğuna ulaşın (ör. Bazel Kuralları Yazarları SIG).
Bayrak sallanıyor
İşaretin varsayılan değerini doğru değerine çevirmeden önce lütfen aşağıdakilerden emin olun:
Ekosistemdeki temel depoları taşınır.
bazelisk-plus-incompatible-flags
hattında, bayrakThe following flags didn't break any passing Bazel team owned/co-owned projects
altında görünmelidir.Yapılacaklar listesindeki tüm sorunlar sabit/kapalı olarak işaretlenir.
Kullanıcı endişeleri ve soruları çözüldü.
İşaret, Bazel'da çevrilmeye hazır ancak Google'da dahili taşıma işlemi engellenmişse lütfen bayrak çevirmenin engellemesini kaldırmak için dahili blazerc
dosyasında bayrak değerini "false" (yanlış) olarak ayarlayın. Böylece, mümkün olan en kısa sürede Bazel kullanıcılarının yeni davranışa varsayılan olarak güvenmelerini sağlayabiliriz.
Varsayılan işareti doğru olarak değiştirirken lütfen:
- Kayıt açıklamasında aşağıdaki biçimi kullanarak
RELNOTES[INC]
kullanın:RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details
Ek açıklamanın geri kalanına ek bilgiler ekleyebilirsiniz. - Kayıtta birleştirilen GitHub sorununun kapatılması için açıklamada
Fixes #xyz
kullanın. - Gerekirse belgeleri inceleyip güncelleyin.
- Bayrağın kaldırılmasını izlemek için yeni bir sorun bildirin
#abc
.
Bayrak kaldırılıyor
Bayrakta çevrildikten sonra bayrak Bazel'dan kaldırılmalıdır. Uyumlu olmayan işareti kaldırmayı planladığınızda:
- Önemli bir uyumsuzluk söz konusuysa, kullanıcıların geçiş yapması için daha fazla zaman tanıyın. İdeal olarak, bayrak en az bir ana sürümde bulunmalıdır.
- İşareti kaldıran kaydetme için, kayıt birleştirildiğinde GitHub sorununun kapatılması için açıklamada
Fixes #abc
kullanın.