Bazel'de zarar verici değişiklikler yapmamız kaçınılmazdır. Tasarımlarımızı değiştirmemiz ve düzgün çalışmayan şeyleri düzeltmemiz gerekecek. Ancak topluluğun ve Bazel ekosisteminin bu değişime ayak uydurabilmesini sağlamamız gerekiyor. Bu amaçla, Bazel projesi geriye dönük uyumluluk politikası benimsemiştir. Bu dokümanda, Bazel katkıda bulunanlarının bu politikaya uymak için Bazel'de önemli bir değişiklik yapma süreci açıklanmaktadır.
GitHub sorunu
Bazel deposunda GitHub sorunu oluşturun. Örneği inceleyin.
Aşağıdakileri yapmanızı öneririz:
Başlık, işaretin adıyla başlar (bayrak adı
incompatible_
ile başlar).incompatible-change
etiketini ekleyin.Açıklamada değişikliğin açıklaması ve ilgili tasarım belgelerinin bağlantısı yer alır.
Açıklama, kullanıcılara kodlarını nasıl güncellemeleri gerektiğini açıklayan bir taşıma tarifi içerir. İdeal olarak, değişiklik mekanik olduğunda bir taşıma aracının bağlantısını ekleyin.
Açıklamada, taşıma işlemini gerçekleştirmeyen kullanıcıların göreceği hata mesajı örneği yer alır. Bu, GitHub sorununu arama motorlarında daha kolay bulunabilir hale getirir. Hata mesajının faydalı olduğundan ve işlem yapılabilir olduğundan emin olun. Mümkünse hata mesajında uyumsuz işaretin adı yer almalıdır.
Taşıma aracı için Buildifier'a katkıda bulunabilirsiniz.
BUILD
, WORKSPACE
ve .bzl
dosyalarına otomatik düzeltmeler uygulayabilir.
Uyarı da bildirebilir.
Uygulama
Bazel'de yeni bir işaret oluşturun. Varsayılan değer false olmalıdır. Yardım metni, GitHub sorununun URL'sini içermelidir. İşaretçi adı incompatible_
ile başladığından meta veri etiketlerine ihtiyaç duyar:
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
İşaretin kısa bir özetini, gönderim açıklamasına ekleyin.
Aşağıdaki formda RELNOTES:
etiketini de ekleyin:
RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
Kodun dokümanlarla tutarsız olduğu bir commit aralığı olmaması için commit, ilgili dokümanları da güncellemelidir. Dokümanlar sürümlere ayrıldığından, dokümanlarda yapılan değişiklikler yanlışlıkla erkenden yayınlanmaz.
Etiketler
Taahhüt birleştirildikten ve uyumsuz değişiklik uygulanmaya hazır hale geldikten sonra GitHub sorununa migration-ready
etiketini ekleyin.
İşaretle ilgili bir sorun bulunursa ve kullanıcıların henüz taşınması beklenmiyorsa:
migration-ready
işaretlerini kaldırın.
İşareti bir sonraki büyük sürümde etkinleştirmeyi planlıyorsanız soruna "breaking-change-X.0" etiketini ekleyin.
Depoları güncelleme
Bazel CI, Bazel@HEAD + Downstream'da önemli projelerin bir listesini test eder. Bunların çoğu genellikle diğer Bazel projelerinin bağımlılığıdır. Bu nedenle, daha geniş bir topluluğa geçişin önündeki engelleri kaldırmak adına bunları taşımak önemlidir. Bu projelerin taşıma durumunu izlemek için bazelisk-plus-incompatible-flags
ardışık düzenini kullanabilirsiniz.
Bu ardışık düzenin işleyiş şeklini buradan inceleyebilirsiniz.
Geliştirici destek ekibimiz migration-ready
etiketini izler. Bu etiketi GitHub sorununa eklediğinizde aşağıdaki işlemleri yaparlar:
Hataların ve taşınması gereken aşağı akış projelerinin listesini takip etmek için GitHub sorununda bir yorum oluşturun (Örneği inceleyin)
Uyumlu olmayan değişikliğiniz nedeniyle bozulan her alt akış projesinin sahiplerini bilgilendirmek için GitHub sorunları oluşturun (örnek)
Hedeflenen yayın tarihinden önce tüm sorunların giderildiğinden emin olmak için takip edin
Aşağı akış ardışık düzeninde projeleri taşıma işlemi uyumsuz değişiklik yazarının sorumluluğu DEĞİLDİR. Ancak taşıma işlemini hızlandırmak ve hem Bazel kullanıcıları hem de Bazel Yeşil Ekibi için işleri kolaylaştırmak amacıyla aşağıdakileri yapabilirsiniz.
Satışa dönük projeleri düzeltmek için halkla ilişkiler belgesi göndermek.
Taşımayla ilgili yardım için Bazel topluluğuna (ör. Bazel Kuralları Yazarları SIG) ulaşın.
Bayrak ters dönüyor
İşaretin varsayılan değerini "true" olarak değiştirmeden önce lütfen aşağıdakilerden emin olun:
Ekosistemdeki temel depolar taşınır.
bazelisk-plus-incompatible-flags
ardışık düzeninde işaret,The following flags didn't break any passing Bazel team owned/co-owned projects
altında görünür.Kontrol listesindeki tüm sorunlar düzeltildi/kapalı olarak işaretlenir.
Kullanıcıların endişeleri ve soruları giderildi.
İşaretçi Bazel'de değiştirilmeye hazırsa ancak Google'daki dahili taşıma işleminde engelleniyorsa lütfen dahili blazerc
dosyasında işaretçi değerini false olarak ayarlayarak işaretçi değişikliğinin engellemesini kaldırın. Bu sayede, Bazel kullanıcılarının mümkün olan en kısa sürede varsayılan olarak yeni davranışı kullanmasını sağlayabiliriz.
Varsayılan işareti "true" (doğru) olarak değiştirirken lütfen şunları yapın:
- Taahhüt açıklamasında
RELNOTES[INC]
ifadesini aşağıdaki biçimde kullanın:RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details
Taahhüt açıklamasının geri kalanına ek bilgiler ekleyebilirsiniz. - Kayıt birleştirildiğinde GitHub sorununun kapatılması için açıklamada
Fixes #xyz
kullanın. - Dokümanları inceleyin ve gerekirse güncelleyin.
- İşaretin kaldırılmasını takip etmek için yeni bir sorun
#abc
gönderin.
İşareti kaldırma
HEAD'da işaret değiştirildikten sonra zaman içinde Bazel'den kaldırılır. Uyumsuz işareti kaldırmayı planladığınızda:
- Önemli bir uyumsuz değişiklik söz konusuysa, taşıma işlemi için kullanıcılara daha fazla zaman bırakabilirsiniz. İdeal olarak işaret, en az bir büyük sürümde kullanılabilir olmalıdır.
- İşareti kaldıran commit için açıklamada
Fixes #abc
kullanın. Böylece, commit birleştirildiğinde GitHub sorunu kapatılır.