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

Bazel'de zarar verici 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 de takip edebildiğinden emin olmamız gerekiyor. Bu amaçla Bazel projesi geriye dönük uyumluluk politikasını benimsemiştir. Bu dokümanda, Bazel katkıda bulunanların bu politikaya uymak için Bazel'de zarar verici değişiklik yapma süreci açıklanmaktadır.

  1. Belge tasarımı politikasına uyun.

  2. GitHub sorunu bildirin.

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

  4. Etiketleri güncelleme

  5. Uyumsuz işareti çevirin.

GitHub sorunu

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

Şunları öneriyoruz:

  • Başlık, bayrağın adıyla başlar (bayrak adı incompatible_ ile başlar).

  • incompatible-change etiketini eklediniz.

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

  • Açıklama, kullanıcılara kodlarını nasıl güncellemeleri gerektiğini açıklayan bir taşıma tarifi içerir. İdeal olarak, değişiklik mekanik olduğunda bir taşıma aracının bağlantısını ekleyin.

  • Açıklamada, kullanıcıların taşıma işlemini gerçekleştirmemeleri durumunda alacakları hata mesajının bir örneği yer alır. Bu sayede GitHub sorunu, arama motorlarından daha kolay keşfedilebilir. Hata mesajının faydalı ve işlem yapılabilir 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 bulunmayı düşünün. BUILD, WORKSPACE ve .bzl dosyalarına otomatik düzeltmeler uygulayabilir. Ayrıca uyarılar da bildirebilir.

Uygulama

Bazel'de yeni bir bayrak oluşturun. Varsayılan değer false olmalıdır. Yardım metni, GitHub sorununun URL'sini içermelidir. Bayrak adı incompatible_ ile başladığından meta veri etiketlerine ihtiyacı vardır:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

Kaydetme açıklamasına işaretin kısa bir özetini ekleyin. RELNOTES: etiketini aşağıdaki forma da ekleyin: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

Kaydın ilgili dokümanları da güncellemesi gerekir, böylece kodun belgelerle tutarsız olduğu kaydetme aralığı kalmaz. Belgelerimizin sürümü oluşturulduğu için dokümanlarda yapılan değişiklikler yanlışlıkla erken kullanıma sunulmaz.

Etiketler

Kaydetme birleştirildikten ve uyumsuz değişiklik uygulanmaya hazır hale geldikten sonra, GitHub sorununa migration-ready etiketini ekleyin.

İşaretle ilgili bir sorun tespit edilirse ve kullanıcıların henüz taşıma işlemi beklenmiyorsa: migration-ready işaretlerini kaldırın.

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

Depoları güncelleme

Bazel CI, önemli projelerin bir listesini Bazel@HEAD + Downstream sayfasında test eder. Çoğu, genellikle diğer Bazel projelerine bağımlıdır. Bu nedenle, göç sürecini daha geniş bir topluluğa yaymak için 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 nasıl çalıştığını buradan kontrol edebilirsiniz.

Aşağı akış hattında projeleri taşımak, tamamen uyumsuz değişiklik yazarının sorumluluğu DEĞİLDİR. Bununla birlikte, taşımayı 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. Uyumsuz değişikliğinizden kaynaklanan aşağı akış projelerinin sahiplerini bilgilendirmek için GitHub sorunları oluşturun.
  2. Aşağı akış projelerini düzeltmek için PR'ler göndermek.
  3. Göç konusunda yardım almak için Bazel topluluğuna ulaşın (ör. Bazel Kuralları Yazarları SIG).

Bayrağı çevirme

İşaretin varsayılan değerini true (doğru) değerine çevirmeden önce lütfen aşağıdakilerden emin olun:

Bayrak Bazel'de çevrilmeye hazır olduğunda ancak Google'ın dahili taşımasında engellenmişse işaret çevirme engelini kaldırmak için lütfen dahili blazerc dosyasında işaret değerini false (yanlış) olarak ayarlayın. Bu sayede Bazel kullanıcılarının mümkün olduğunca erken bir şekilde varsayılan olarak yeni davranışa dayanmasını sağlayabiliriz.

İşaretleme varsayılanını doğru olarak değiştirirken lütfen:

  • 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 daha fazla bilgi ekleyebilirsiniz.
  • Açıklamada Fixes #xyz kullanın. Böylece, kaydetme birleştirildiğinde GitHub sorununun kapatılmasını sağlayabilirsiniz.
  • Belgeleri inceleyin ve gerekiyorsa güncelleyin.
  • İşaretin kaldırılmasını takip etmek için yeni bir sorun #abc bildirin.

Bayrak kaldırma

Bayrak HEAD noktasında çevirildikten sonra, sonunda Bazel'den kaldırılacaktır. Uyumsuz işareti kaldırmayı planladığınızda:

  • Önemli ve uyumsuz bir değişiklik söz konusuysa kullanıcılara taşıma işlemi için daha fazla zaman ayırabilirsiniz. İdeal olarak, bayrağın en az bir ana yayında bulunması gerekir.
  • İşareti kaldıran kaydetme için açıklamada Fixes #abc kullanın. Böylece kaydetme birleştirildiğinde GitHub sorunu kapatılır.