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

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. Yine de topluluk ve Bazel ekosisteminin aynı yoldan devam edebilmesini sağlamamız gerekiyor. Bu amaçla, Bazel projesi geriye dönük uyumluluk politikası benimsemiştir. Bu dokümanda, Bazel'e katkıda bulunanların bu politikaya uymak için Bazel'de zarar veren bir değişiklik yapması için gereken süreç açıklanmaktadır.

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

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

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

• incompatible-change etiketini ekleyin.

• Açıklamada, değişiklikle ilgili bir açıklama 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ıyla ilgili bir örnek yer alır. 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ü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. 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çi adı incompatible_ ile başladığından meta veri etiketlerine ihtiyaç duyar:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

İşaretin kısa bir özetini, gönderim açıklamasına 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. Belgelerimizin sürümü bulunduğundan, dokümanlarda yapılan değişiklikler istemeden erken yayınlanmayacaktır.

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.

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

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ığıdır. Bu nedenle, daha geniş bir topluluğa 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 burada inceleyebilirsiniz.

Aşağı akış ardışık düzeninde projeleri taşıma işlemi, tamamen uyumsuz değişiklik yazarının sorumluluğunda 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. Uyumsuz değişikliğinizden dolayı bozulan aşağı akış projelerinin sahiplerini bilgilendirmek için GitHub sorunlarını bildirin.
2. Satışa dönük projeleri düzeltmek için halkla ilişkiler belgesi göndermek.
3. Taşımayla ilgili yardım için Bazel topluluğuna (ör. Bazel Kuralları Yazarları SIG) ulaşın.

Bayrak ters dönüyor

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

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

• 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, Bazel kullanıcılarının mümkün olan en kısa sürede varsayılan olarak yeni davranışı kullanmasını 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.
• Kayıt birleştirildiğinde GitHub sorununun kapatılması için açıklamada Fixes #xyz kullanın.
• 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

HEAD'da işaret 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.