Zarar veren değişiklikleri kullanıma sunma kılavuzu

Bazel'de zarar veren değişiklikler yapmamız kaçınılmazdır. Tasarımlarımızı değiştirmemiz ve tam olarak çalışmayan şeyleri düzeltmemiz gerekecek. Ancak topluluğun ve Bazel ekosisteminin bu değişiklikleri takip edebilmesini sağlamamız gerekiyor. Bu amaçla Bazel projesi, geriye dönük uyumluluk politikası benimsemiştir. Bu belgede, Bazel katkıda bulunanların bu politikaya uymak için Bazel'de uyumluluğu bozan bir değişiklik yapma süreci açıklanmaktadır.

1. Tasarım belgesi politikasına uyun.

2. GitHub'da sorun bildirin.

3. Değişikliği uygulayın.

4. Etiketleri güncelleyin.

5. Depoları güncelleyin.

6. Uyumsuzluk işaretini kaldırın.

GitHub sorunu

Bazel deposunda GitHub sorunu bildirin. Örneği inceleyin.

Şunları yapmanızı öneririz:

• Başlık, işaretin adıyla başlar (işaret adı incompatible_ ile başlar).

• incompatible-change etiketini eklersiniz.

• Açıklamada, değişikliğin açıklaması ve ilgili tasarım belgelerinin bağlantısı yer alır.

• Açıklamada, kullanıcılara kodlarını nasıl güncellemeleri gerektiğini açıklayan bir taşıma tarifi yer alır. İ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 yapmayan kullanıcıların alacağı hata mesajına dair bir örnek yer alıyor. Bu, GitHub sorununu arama motorlarında daha kolay keşfedilebilir hale getirir. Hata mesajının yararlı ve uygulanabilir olduğundan emin olun. Mümkün olduğunda hata mesajı, uyumsuz işaretin adını içermelidir.

Taşıma aracı için Buildifier'a katkıda bulunabilirsiniz. BUILD, WORKSPACE ve .bzl dosyalarına otomatik düzeltmeler uygulayabilir. Uyarıları da bildirebilir.

Uygulama

Bazel'de yeni bir işaret 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ığı için meta veri etiketleri gerekir:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

Commit açıklamasında, işaretin kısa bir özetini ekleyin. Ayrıca, aşağıdaki biçimde RELNOTES: ekleyin: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

Ayrıca, kodun dokümanlarla tutarsız olduğu bir commit penceresi olmaması için commit, ilgili dokümanları da güncellemelidir. Dokümanlarımız sürüm kontrolüne tabi olduğundan dokümanlarda yapılan değişiklikler yanlışlıkla erken yayınlanmaz.

Etiketler

Taahhüt birleştirildikten ve uyumsuz değişiklik uygulanmaya hazır olduğunda GitHub sorununa migration-ready etiketini ekleyin.

İşaretle ilgili bir sorun bulunursa ve kullanıcıların henüz taşıma yapması beklenmiyorsa: işaretleri kaldırın migration-ready.

Bir sonraki büyük sürümde işareti ters çevirmeyi planlıyorsanız soruna "breaking-change-X.0" etiketini ekleyin.

Depoları güncelleme

Bazel CI, Bazel@HEAD + Downstream adresinde önemli projelerin bir listesini test eder. Bunların çoğu genellikle diğer Bazel projelerinin bağımlılıklarıdır. Bu nedenle, daha geniş topluluğun geçişini engellememek için bunları taşımanız önemlidir. Bu projelerin taşıma durumunu izlemek için bazelisk-plus-incompatible-flags işlem hattını kullanabilirsiniz. Bu işlem hattının nasıl çalıştığını buradan öğrenebilirsiniz.

Geliştirici destek ekibimiz migration-ready etiketini izler. Bu etiketi GitHub sorununa eklediğinizde aşağıdaki işlemler yapılır:

1. Başarısızlıkların listesini ve taşınması gereken aşağı akış projelerini izlemek için GitHub sorununda yorum oluşturun (örneğe bakın).

2. Uyumsuz değişikliğinizden etkilenen her bir aşağı akış projesinin sahiplerini bilgilendirmek için GitHub sorunları oluşturun (örneğe bakın).

3. Hedef yayın tarihinden önce tüm sorunların ele alındığından emin olmak için takip edin.

Aşağı akış hattındaki projeleri taşıma işlemi TAMAMEN uyumsuz değişikliği yapan kişinin sorumluluğunda DEĞİLDİR. Ancak taşıma işlemini hızlandırmak ve hem Bazel kullanıcılarının hem de Bazel Green Team'in işini kolaylaştırmak için aşağıdakileri yapabilirsiniz.

1. Aşağı akış projelerini düzeltmek için PR gönderin.

2. Taşıma konusunda yardım almak için Bazel topluluğuna (ör. Bazel Rules Authors SIG) ulaşın.

Bayrağı ters çevirme

İşaretin varsayılan değerini "true" olarak değiştirmeden önce lütfen şunlardan emin olun:

• Ekosistemdeki temel depolar taşınır.

  bazelisk-plus-incompatible-flags işlem hattında, 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/kapatıldı olarak işaretlenir.

• Kullanıcıların endişeleri ve soruları giderildi.

Bazel'de geçişe hazır olan ancak Google'daki dahili taşıma nedeniyle engellenen bir özellik varsa lütfen dahili blazerc dosyasında özellik değerini false olarak ayarlayarak özellik geçiş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ışa bağlı kalmasını sağlayabiliriz.

İşaretin varsayılan değerini "true" olarak değiştirirken lütfen:

• Commit açıklamasında RELNOTES[INC] öğesini aşağıdaki biçimde kullanın: RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details Commit açıklamasının geri kalanına ek bilgiler ekleyebilirsiniz.
• Açıklamada Fixes #xyz kullanın. Böylece, commit birleştirildiğinde GitHub sorunu kapatılır.
• Gerekirse dokümanları inceleyin ve güncelleyin.
• İşaretin kaldırılmasını takip etmek için #abc yeni bir sorun kaydı oluşturun.

İşareti kaldırma

HEAD'de işaret değiştirildikten sonra Bazel'den kaldırılmalıdır. Uyumsuzluk işaretini kaldırmayı planladığınızda:

• Büyük bir uyumsuzluk değişikliği söz konusuysa kullanıcıların geçiş yapması için daha fazla zaman tanımayı düşünebilirsiniz. İdeal olarak, işaret en az bir ana sürümde kullanılabilir olmalıdır.
• İşleme birleştirildiğinde GitHub sorununun kapatılması için açıklamada Fixes #abc işaretini kullanarak işleme bayrağını kaldırın.