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

Sorun bildirin Kaynağı göster

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.

  1. Doküman tasarımı politikasını uygulayın.

  2. GitHub sorunu bildirin.

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

  4. Etiketleri güncelleyin.

  5. Veri depolarını güncelleyin.

  6. Uyumsuz işareti çevirin.

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:

  1. 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)

  2. Uyumsuz değişiklik nedeniyle bozulan her aşağı akış projesini sahiplerine bildirmek için GitHub sorunlarını gönderin (örneği inceleyin)

  3. 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.

  1. Satışa dönük projeleri düzeltmek için halkla ilişkiler çalışmaları gönderin.

  2. 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, bayrak The 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.