Kullanıcılara yönelik bir özelliği eklemeyi, değiştirmeyi veya kaldırmayı ya da Bazel'e önemli bir mimari değişiklik yapmayı planlıyorsanız değişikliği göndermeden önce bir tasarım belgesi yazmanız ve incelenmesini sağlamanız gerekir.
Önemli değişikliklere ilişkin bazı örnekleri aşağıda bulabilirsiniz:
- Yerel derleme kuralları ekleme veya silme
- Yerel kurallarda yapılan önemli değişiklikler
- Birden fazla kuralın davranışını etkileyen yerel derleme kuralı semantiğinde yapılan değişiklikler
- Bazel'in kural tanımı API'sinde yapılan değişiklikler
- Bazel'ın diğer sistemlere bağlanmak için kullandığı API'lerde yapılan değişiklikler
- Starlark dili, anlamlar veya API'ler ile ilgili değişiklikler
- Bazel performansı veya bellek kullanımı üzerinde geniş çaplı bir etki yaratabilecek değişiklikler (iyi veya kötü yönde)
- Yaygın olarak kullanılan dahili API'lerdeki değişiklikler
- İşaretler ve komut satırı arayüzünde yapılan değişiklikler.
Tasarım incelemelerinin nedenleri
Bir tasarım belgesi yazarken, diğer Bazel geliştiricileriyle koordineli bir şekilde Bazel'in çekirdek ekibinden yardım isteyebilirsiniz. Örneğin, bir teklif BUILD, WORKSPACE veya Bzl dosyalarında bulunan herhangi bir işlevi veya nesneyi eklediğinde, kaldırdığında ya da değiştirdiğinde Starlark ekibini incelemeci olarak ekleyin. Tasarım belgeleri gönderilmeden önce incelenir çünkü:
- Bazel çok karmaşık bir sistemdir. Görünüşte zararsız olan yerel değişikliklerin önemli küresel sonuçları olabilir.
- Ekip, kullanıcılardan çok sayıda özellik isteği alır. Bu tür isteklerin, yalnızca teknik uygulanabilirlik açısından değil, diğer özellik istekleri açısından da önem açısından değerlendirilmesi gerekir.
- Bazel özellikleri, çekirdek ekibin dışındaki kişiler tarafından sıklıkla uygulanır. Bu tür katkıda bulunanların Bazel uzmanlık düzeyleri çok çeşitlidir.
- Bazel ekibinin uzmanlık düzeyi değişiklik gösterir ve ekipteki hiçbir üye Bazel'in her köşesini tam olarak bilemez.
- Bazel'da yapılan değişiklikler geriye dönük uyumluluğu dikkate almalı ve değişiklikleri bozmamalıdır.
Bazel'in tasarım incelemesi politikası, aşağıdakilerin gerçekleşme olasılığını en üst düzeye çıkarmaya yardımcı olur:
- tüm özellik istekleri temel düzeyde incelemeden geçer.
- ancak işe yaramayabilecek bir uygulamaya yatırım yapmadan önce tasarımlarda doğru kişilerin fikir alışverişinde bulunacağı anlamına gelir.
Başlamanıza yardımcı olması için Bazel Teklifler Deposu'ndaki tasarım belgelerine göz atın. Tasarımlar devam ettiğinden uygulama ayrıntıları zamanla ve geri bildirimlerle değişebilir. Yayınlanan tasarım belgeleri ilk tasarımı yakalar, tasarımlar uygulanırken devam eden değişiklikleri değil. Mevcut Bazel işlevlerinin açıklamaları için her zaman dokümanlara bakın.
Katkıda Bulunan İş Akışı
Katkıda bulunan olarak bir tasarım belgesi yazabilir, çekme istekleri gönderebilir ve teklifiniz için incelemeciler isteyebilirsiniz.
Tasarım belgesini yazma
Tüm tasarım belgeleri, aşağıdakileri içeren bir üstbilgiye sahip olmalıdır:
- author
- son büyük değişikliğin tarihi
- bir (yalnızca bir) potansiyel müşteri inceleme uzmanı dahil olmak üzere
- mevcut durum (taslak, inceleniyor, onaylandı, reddedildi, uygulanıyor, uygulandı)
- tartışma ileti dizisinin bağlantısı (duyurudan sonra eklenecek)
Belge, herkesin okuyabileceği bir Google Dokümanı olarak veya Markdown kullanılarak yazılabilir. Markdown / Google Dokümanlar karşılaştırması için aşağıdaki bilgileri okuyun.
Kullanıcıların görebileceği etkiye sahip teklifler, geriye dönük uyumluluk üzerindeki etkiyi gösteren bir bölüme (ve gerekirse kullanıma sunma planına) sahip olmalıdır.
Çekme İsteği Oluşturma
Dokümanı tasarım dizinine eklemek için bir çekme isteği (PR) oluşturarak tasarım dokümanınızı paylaşın. Markdown dosyanızı veya bir doküman bağlantısını halkla ilişkiler kuruluşunuza ekleyin.
Mümkün olduğunda bir potansiyel inceleme uzmanı seçin ve diğer incelemecileri cc bölümüne ekleyin. Baş inceleme uzmanı seçmezseniz bir Bazel bakimisi halkla ilişkiler ekibine bir kişi atar.
PR'nizi oluşturduktan sonra incelemeciler kod incelemesi sırasında ön yorumlar yapabilir. Örneğin, baş incelemeci ek incelemeciler önerebilir veya eksik bilgileri vurgulayabilir. Baş incelemeci, inceleme sürecinin başlayacağını düşündüğünde PR'yi onaylar. Bu, teklifin mükemmel olduğu veya onaylanacağı anlamına gelmez. Bu, teklifin tartışmaya başlamak için yeterli bilgi içerdiği anlamına gelir.
Yeni teklifi duyurun
PR gönderildiğinde bazel-dev'e bir duyuru gönderin.
Bazel son kullanıcılarından geri bildirim almak için diğer grupları kopyalayabilirsiniz (örneğin, bazel-tartışma).
İncelemecilerle birlikte çalışın
İlgilenen herkes teklifinize yorum yapabilir. Soruları yanıtlamaya, teklifi açıklığa kavuşturmaya ve kaygıları ele almaya çalışın.
Tartışma, duyuru ileti dizisinde yapılmalıdır. Teklif bir Google Dokümanı'ndaysa bunun yerine yorumlar kullanılabilir (Anonim yorumlara izin verildiğini unutmayın).
Durumu güncelle
Yineleme tamamlandığında teklifin durumunu güncellemek için yeni bir PR oluşturun. PR'yi aynı potansiyel incelemeciye gönderin ve diğer incelemecileri cc'ye ekleyin.
Baş incelemeci, teklifi resmi olarak kabul etmek için diğer incelemecilerin kararı kabul etmesini sağladıktan sonra halkla ilişkiler uzmanını onaylar.
İlk duyuruyla teklifin onaylanması arasında en az 1 hafta olmalıdır. Bu, kullanıcıların belgeyi okumak ve endişelerini paylaşmak için yeterli zamana sahip olmasını sağlar.
Uygulama, teklif kabul edilmeden önce (ör. kavram kanıtlama veya deneme) başlayabilir. Ancak değişikliği, inceleme tamamlanmadan gönderemezsiniz.
Potansiyel müşteri inceleme uzmanı seçme
Potansiyel müşteri inceleme uzmanı, aşağıdaki özelliklere sahip bir alan uzmanı olmalıdır:
- İlgili alt sistemler hakkında bilgi sahibi olma
- Nesnel ve yapıcı geri bildirim verme becerisine sahip olma
- Süreci yönetmek için inceleme süresinin tamamı boyunca kullanılabilir
Kişilerde çeşitli ekip etiketleri olup olmadığını kontrol edebilirsiniz.
Markdown ve Google Dokümanlar
Her ikisi de kabul edildiğinden, sizin için en uygun olanın hangisi olduğuna karar verin.
Google Dokümanlar'ı kullanmanın avantajları:
- Başlaması kolay olduğundan beyin fırtınası için kullanışlıdır.
- Ortak çalışmayla düzenleme
- Hızlı yineleme.
- Kolay düzenleme önerisinde bulunmanın yolu.
Markdown dosyalarını kullanmanın avantajları:
- Bağlantı oluşturmak için URL'leri temizleyin.
- Düzeltmelerin açık kaydı.
- Bir bağlantıyı yayınlamadan önce erişim haklarını ayarlamayı unutmayın.
- Arama motorları ile kolayca aranabilir.
- Geleceğe hazır: Düz metin, belirli bir aracın menfaati değildir ve internet bağlantısı gerektirmez.
- Yazar artık yakında olmasa bile bu e-postaları güncellemek mümkündür.
- Otomatik olarak işlenebilirler (ör. geçersiz bağlantıları güncelleme/algılama, yazarların listesini getirme vb.).
Önce bir Google Dokümanı üzerinde iterasyon yapmayı, ardından bunu daha sonra tekrarlanmak için Markdown'a dönüştürmeyi seçebilirsiniz.
Google Dokümanlar'ı kullanma
Tutarlılık için Bazel tasarım dokümanı şablonunu kullanın. Gerekli başlığı içerir ve Bazel ile ilgili diğer dokümanlarla görsel tutarlılık oluşturur. Bunu yapmak için Dosya > Kopya oluştur'u veya tasarım dokümanı şablonunun bir kopyasını oluşturmak için bu bağlantıyı tıklayın.
Belgenizi herkes tarafından okunabilir hale getirmek için Paylaş > Gelişmiş > Değiştir...'i tıklayın ve "Açık - Bağlantıya sahip olan herkes"i seçin. Dokümanda yorumlara izin verirseniz, Google Hesabı olmasa bile herkes anonim olarak yorum yapabilir.
Markdown'ı kullanma
Belgeler GitHub'da depolanır ve Markdown'ın GitHub türünü (Spesifikasyon) kullanır.
Mevcut bir dokümanı güncellemek için halkla ilişkiler oluşturun. Önemli değişiklikler, belge incelemecileri tarafından incelenmelidir. Küçük değişiklikler (yazım hataları, biçimlendirme gibi) herkes tarafından onaylanabilir.
İncelemeci iş akışı
İncelemeci tasarım dokümanlarını yorumlar, inceler ve onaylar.
Genel incelemeci sorumlulukları
Tasarım belgelerini incelemek, gerekirse ek bilgi istemek ve inceleme sürecinden geçen bir tasarımı onaylamak sizin sorumluluğunuzdadır.
Yeni bir teklif aldığınızda
- Dokümana hızlıca göz atın.
- Kritik bilgilerin eksik olup olmadığını veya tasarımın projenin hedeflerine uygun olup olmadığını yorumlayın.
- Başka incelemeciler önerin.
- PR'yi incelenmeye hazır olduğunda onaylayın.
İnceleme süreci sırasında
- Sorunlu veya açıklığa kavuşturulması gereken sorunlar hakkında tasarım yazarıyla diyalog kurun.
- Uygunsa tasarımdan haberdar olması gereken incelemeci olmayan kişilerin yorumlarını davet edin.
- Onay ön koşulu olarak hangi yorumların yazar tarafından ele alınması gerektiğine karar verin.
- Teklifin mevcut durumundan memnun olduğunuzda tartışma ileti dizisine "LGTM" (Bana İyi Görünüyor) yazın.
Tüm tasarım incelemesi istekleri için bu süreci izleyin. Tasarım dizininde yer almayan, Bazel'i etkileyen tasarımları onaylamayın.
Baş incelemecinin sorumlulukları
Beklemedeki bir tasarımın uygulanmasıyla ilgili olarak "harekete geçme" kararını vermek sizin sorumluluğunuzdadır. Bunu yapamıyorsanız uygun bir yetki verilmiş kişi belirlemeniz (PR'yi yetki verilmiş kişiye yeniden atamanız) veya hatayı daha ayrıntılı bir şekilde ele alınması için bir Bazel yöneticisine yeniden atamanız gerekir.
İnceleme süreci sırasında
- Yorum ve tasarım yineleme sürecinin yapıcı bir şekilde ilerlemesini sağlayın.
- Onay almadan önce, diğer incelemecilerin endişelerinin giderildiğinden emin olun.
Tüm incelemeciler tarafından onaylandıktan sonra
- Posta listesindeki duyurunun üzerinden en az 1 hafta geçtiğinden emin olun.
- Halkla ilişkiler ekibinin durumu güncellediğinden emin olun.
- Teklif yazarı tarafından gönderilen PR'yi onaylayın.
Tasarımlar reddediliyor
- Halkla ilişkiler yazarının bir halkla ilişkiler (PR) gönderdiğinden emin olun veya onlara bir PR gönderin.
- PR, dokümanın durumunu günceller.
- Belgeye tasarımın mevcut haliyle neden onaylanamayacağını açıklayan ve varsa sonraki adımları özetleyen bir yorum ekleyin (ör. "geçersiz varsayımları yeniden ziyaret edin ve yeniden gönderin").