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

Sorun bildirin Kaynağı göster Gece · 7,4 , 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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 devam etmesini sağlamak için. Bu doğrultuda Bazel projesinde, geriye dönük uyumluluk politikasına uygun olmalıdır. Bu dokümanda, Bazel'a katkıda bulunanların sorun çözme süreci bu politikaya uymak için Bazel'de değişiklik yapılmasına izin veriyoruz.

  1. Tasarım dokümanı politikasını uygulayın.

  2. GitHub'da sorun bildirin.

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

  4. Etiketleri güncelleyin.

  5. Depoları güncelleyin.

  6. Uyumsuz işareti çevirin.

GitHub sorunu

GitHub sorunu bildirin inceleyebilirsiniz. Örneği inceleyin.

Şunları yapmanızı öneririz:

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

  • Etiketi siz eklersiniz incompatible-change.

  • Açıklama, değişiklikle ilgili bir açıklama ve alakalı bir en iyi uygulamaları paylaşacağım.

  • Açıklamada, kullanıcılara kodlarını nasıl güncellemeleri gerektiğini açıklayan bir taşıma tarifi bulunur. İdeal olarak değişiklik mekanikse, bir taşıma aracını kullanın.

  • Açıklamada, kullanıcıların aşağıdaki durumlarda alacakları hata mesajıyla ilgili bir örnek yer alır: taşınmazlar. Bu, GitHub sorununun arama motorlarında daha kolay bulunmasını sağlar. Hata mesajının faydalı olduğundan ve işlem yapılabilir olduğundan emin olun. Mümkün olduğunda hata mesajı, uyumlu olmayan işaretin adını içermelidir.

Taşıma aracı için şunları yapabilirsiniz: Derleyici. BUILD, WORKSPACE ve .bzl dosyalarına otomatik düzeltmeler uygulayabilir. Uyarı da bildirebilir.

Uygulama

Bazel'de yeni bayrak oluşturun. Varsayılan değer false (yanlış) olmalıdır. Yardım metni, GitHub sorununun URL'sini içermelidir. İşaret adı incompatible_, meta veri etiketleri gerektiriyor:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

Kaydetme açıklamasına bayrağın kısa bir özetini 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ın sürümü oluşturulmuşsa dokümanlarda yapılan değişikliklerin yanlışlıkla yapılmaması erken yayınlanmış olabilir.

Etiketler

Kaydetme birleştirilip uyumlu olmayan değişiklik uygulanmaya hazır olduğunda etiketi ekleyin. migration-ready konuşacağız.

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

Bir sonraki ana sürümde işareti değiştirmeyi planlıyorsanız "breaking-change-X.0" etiketini ekleyin. dikkate almalısınız.

Kod depolarını 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ıklarıdır. Bu nedenle, daha geniş bir topluluk için taşıma işleminin engelini kaldırmak amacıyla bunların 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 aşağıdaki işlemleri yaparlar:

  1. GitHub sorununda, başarısızlıkların ve taşınması gereken alt projelerin listesini izlemek için bir yorum oluşturun (örneke bakın)

  2. Uyumlu olmayan değişikliğiniz nedeniyle bozulan her alt projenin sahiplerini bilgilendirmek için GitHub sorunları oluşturun (örnek)

  3. 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 tamamen 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ının hem de Bazel Yeşil Ekibi'nin hayatını kolaylaştırmak için aşağıdakileri yapabilirsiniz.

  1. Alttaki projeleri düzeltmek için PR gönderin.

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

Bayrak ters dönüyor

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

  • Ekosistemdeki çekirdek depolar taşınır.

    bazelisk-plus-incompatible-flags ardışık düzeninde, bayrak The following flags didn't break any passing Bazel team owned/co-owned projects altında görünecektir.

  • Kontrol listesindeki tüm sorunlar düzeltildi/kapatıldı olarak işaretlenir.

  • Kullanıcı endişeleri ve soruları çözüldü.

İşaret Bazel'de açılmaya hazır olduğunda ancak Google'daki dahili taşıma işleminde engellendiğinde, bayrak çevirme engelini kaldırmak için dahili blazerc dosyasında bayrak değerini false olarak ayarlamayı lütfen düşünün. Bu sayede, mümkün olan en kısa sürede Bazel kullanıcılarının varsayılan olarak yeni davranışa güvenmesini sağlayabiliriz.

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

  • Taahhüt açıklamasında RELNOTES[INC] öğesini şu biçimdedir: 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.
  • GitHub sorununun kapatılması için açıklamada Fixes #xyz kullanın kayıt birleştirildiğinde.
  • Gerekirse belgeleri inceleyin ve güncelleyin.
  • Bayrağın kaldırılmasını takip etmek için yeni bir sorun #abc oluşturun.

İşareti kaldırma

İşaretçi HEAD'de değiştirildikten sonra zaman içinde Bazel'den kaldırılır. Uyumlu değil işaretini 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.