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

Sorun bildir Kaynağı göster Gece · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Bazel'de zarar verici değişiklikler yapmamız kaçınılmazdır. Yapmamız gereken tasarımlarımızı değiştirebilir ve düzgün çalışmayan şeyleri düzeltebiliriz. 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ına uyun.

  2. GitHub sorunu 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.

Aşağıdakileri yapmanızı öneririz:

  • Başlık, bayrağın adıyla başlar (bayrak adı incompatible_) bilgileri gösterilir.

  • Etiketi siz eklersiniz incompatible-change.

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

  • Açıklama, kullanıcılara nasıl taşımaları gerektiğini açıklayan bir taşıma tarifi içerir. onların kodunu güncellememiz gerekir. İdeal olarak değişiklik mekanikse, bir taşıma aracını kullanın.

  • Açıklamada, kullanıcıların aşağıdaki işlemleri gerçekleştirmeleri durumunda alacakları hata mesajıyla ilgili bir örnek yer alır: taşınmazlar. Bu, GitHub sorununun şuradan bulunabilir hale gelmesini sağlar: yardımcı olur. Hata mesajının faydalı olduğundan ve işlem yapılabilir olduğundan emin olun. Mümkün olduğunda, hata mesajında uyumsuz tıklayın.

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. RELNOTES: hizmetini aşağıdaki formda da ekleyin: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

Taahhüt ayrıca ilgili belgeleri güncelleyerek kodun dokümanlarla tutarsız olduğu kaydetme işlemi penceresi. dokümanların sürümü oluşturulmuşsa, dokümanlarda yapılan değişiklikler yanlışlıkla yapılmayacaktır erken ortaya çıkmıştır.

Etiketler

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

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

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, en önemli projelerin bir listesini Bazel@HEAD + Aşağı akış. Bunların çoğu genellikle Bu nedenle, daha geniş bir topluluğa yönelik 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 kontrol edebilirsiniz.

Geliştirici destek ekibimiz, migration-ready etiketini izler. GitHub sorununa etiket eklediğinizde şu işlemler gerçekleştirilir:

  1. Hataların ve taşınması gereken aşağı akış projelerinin listesini takip etmek için GitHub sorununda bir yorum oluşturun (Örneği inceleyin)

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

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

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

  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ıların 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.

Varsayılan işareti "true" (doğru) olarak değiştirirken lütfen şunları yapın:

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

Bayrak kaldırılıyor

İşaret HEAD konumunda ters çevrildikten sonra, nihayetinde Bazel'den kaldırılması gerekir. 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 ana sürümde bulunmalıdır.
  • İşareti kaldıran kayıt için açıklama bölümünde Fixes #abc kullanın kayıt birleştirildiğinde GitHub sorununun kapatılmasını sağlar.