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

Bazel'de zarar veren 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 bu değişiklikleri takip edebilmesini sağlamamız gerekiyor. Bu amaçla, Bazel projesi geriye dönük uyumluluk politikası benimsemiştir. Bu belgede, Bazel katkıda bulunanların bu politikaya uymak için Bazel'de önemli bir değişiklik yapma süreci açıklanmaktadır.

1. Tasarım belgesi politikasına uyun.

2. GitHub'da sorun bildirin.

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

4. Etiketleri güncelleyin.

5. Kod depolarını güncelleyin.

6. Uyumsuzluk işaretini kaldırın.

GitHub sorunu

Bazel deposunda GitHub sorunu bildirin. Örneği inceleyin.

Şunları yapmanızı öneririz:

• Başlık, işaretin adıyla başlar (işaret 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çıklama, kullanıcılara kodlarını nasıl güncelleyeceklerini 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, taşıma işlemi yapmayan kullanıcıların alacağı hata mesajına dair bir örnek yer alıyor. Bu sayede, GitHub sorunu arama motorlarında daha kolay bulunabilir. Hata mesajının yararlı ve uygulanabilir olduğundan emin olun. Mümkün olduğunda hata mesajı, uyumsuz işaretin adını içermelidir.

Taşıma aracı için Buildifier'a katkıda bulunabilirsiniz. BUILD, WORKSPACE ve .bzl dosyalarına otomatik düzeltmeler uygulayabilir. Uyarıları da bildirebilir.

Uygulama

Bazel'de yeni bir işaret oluşturun. Varsayılan değer false olmalıdır. Yardım metninde GitHub sorununun URL'si yer almalıdır. İşaret adı incompatible_ ile başladığı için meta veri etiketleri gerekir:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

Commit açıklamasında, işaretin kısa bir özetini ekleyin. Ayrıca, aşağıdaki biçimde RELNOTES: ekleyin: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

Ayrıca, kodun dokümanlarla tutarsız olduğu bir commit penceresi olmaması için commit, ilgili dokümanları da güncellemelidir. Dokümanlarımız sürüm kontrolüne tabi olduğundan dokümanlarda yapılan değişiklikler yanlışlıkla erken yayınlanmaz.

Etiketler

Taahhüt birleştirildikten ve uyumsuz değişiklik uygulanmaya hazır olduğunda GitHub sorununa migration-ready etiketini ekleyin.

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

Bir sonraki büyük sürümde işareti ters çevirmeyi planlıyorsanız soruna "breaking-change-X.0" etiketini ekleyin.

Depoları güncelleme

Bazel CI, Bazel@HEAD + Downstream adresinde ö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ş topluluk için geçişin önünü açmak üzere bunları taşımak önemlidir. Bu projelerin taşıma durumunu izlemek için bazelisk-plus-incompatible-flags işlem hattını kullanabilirsiniz. Bu işlem hattının nasıl çalıştığını buradan öğrenebilirsiniz.

Geliştirici destek ekibimiz migration-ready etiketini izler. Bu etiketi GitHub sorununa eklediğinizde aşağıdaki işlemler yapılır:

1. Başarısızlıkların listesini ve taşınması gereken aşağı akış projelerini izlemek için GitHub sorununda bir yorum oluşturun (örneğe bakın).

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

3. Hedef yayın tarihinden önce tüm sorunların ele alındığından emin olmak için takip edin.

Aşağı akış hattındaki 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 Green Team'in işini kolaylaştırmak için aşağıdakileri yapabilirsiniz.

1. Aşağı akış projelerini düzeltmek için PR gönderin.

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

İşareti geri alma

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

• Ekosistemdeki temel depolar taşınır.

  bazelisk-plus-incompatible-flags işlem hattında, işaret The following flags didn't break any passing Bazel team owned/co-owned projects altında görünmelidir.

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

• Kullanıcıların endişeleri ve soruları giderildi.

Bazel'de özellik etkinleştirilmeye hazır olduğunda ancak Google'daki dahili taşıma nedeniyle engellendiğinde, lütfen dahili blazerc dosyasında özellik değerini false olarak ayarlayarak özellik etkinleştirme işleminin engelini kaldırın. Bunu yaparak Bazel kullanıcılarının mümkün olan en kısa sürede varsayılan olarak yeni davranışa bağlı kalmasını sağlayabiliriz.

Varsayılan işareti true olarak değiştirirken lütfen:

• Commit açıklamasında RELNOTES[INC] simgesini aşağıdaki biçimde kullanın: RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details Commit açıklamasının geri kalanına ek bilgiler ekleyebilirsiniz.
• Açıklamada Fixes #xyz kullanın. Böylece, commit birleştirildiğinde GitHub sorunu kapatılır.
• Gerekirse dokümanları inceleyin ve güncelleyin.
• İşaretin kaldırılmasını takip etmek için #abc yeni bir sorun kaydı oluşturun.

İşareti kaldırma

HEAD'de işaret değiştirildikten sonra Bazel'den kaldırılması gerekir. Uyumsuzluk işaretini kaldırmayı planladığınızda:

• Büyük bir uyumsuzluk değişikliği söz konusuysa kullanıcıların geçiş yapması için daha fazla zaman tanımayı düşünebilirsiniz. İdeal olarak, işaret en az bir ana sürümde kullanılabilir olmalıdır.
• İşlemeyi birleştirdiğinizde GitHub sorununun kapatılması için açıklamada Fixes #abc işaretini kullanarak işleme bayrağını kaldırın.