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

Sorun bildir Kaynağı görüntüleyin Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Bazel'de önemli değişiklikler yapmamız kaçınılmaz. 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.

  1. Tasarım dokümanı 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 tersine çevirin.

GitHub sorunu

Bazel deposunda GitHub sorunu oluşturun. Örneği inceleyin.

Şunları yapmanızı öneririz:

  • Başlık, işaretin adıyla başlar (bayrak 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 bulunur. İ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 sorununun arama motorlarında daha kolay bulunmasını sağlar. Hata mesajının yararlı ve uygulanabilir 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. Ayrıca uyarıları 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 adı incompatible_ ile başladığından meta veri etiketleri gerektirir:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

İşaretin kısa bir özetini, gönderim açıklamasına ekleyin. Aşağıdaki forma RELNOTES: değerini 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: İşaretleri kaldırın migration-ready.

İş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ıklarıdır. Bu nedenle, daha geniş bir topluluk için taşıma işleminin engelini kaldırmak amacıyla bu projeleri 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:

  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. Uyumlu olmayan değişikliğiniz nedeniyle bozulan her alt akış projesinin sahiplerini bilgilendirmek için GitHub sorunları oluşturun (örnek)

  3. Hedef yayın tarihinden önce tüm sorunların giderildiğinden emin olmak için takip edin

Aşağı akış ardışık düzenindeki projeleri taşımak, uyumsuz değişiklik yazarının tamamen 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 Ekibi'nin işini kolaylaştırmak için aşağıdakileri yapabilirsiniz.

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

  2. Taşımayla ilgili yardım için Bazel topluluğuna (ör. Bazel Kuralları Yazarları SIG) ulaşın.

İşareti çevirme

İş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, 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] 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.
  • GitHub sorununun, birleştirme işlemi tamamlandığında 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 ana sürümde bulunmalı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.