Kullanıcılara yönelik bir özellik eklemeyi, değiştirmeyi veya kaldırmayı ya da Bazel'de önemli bir mimari değişiklik yapmayı planlıyorsanız değişikliği göndermeden önce bir tasarım belgesi yazmanız ve bu belgeyi incelemeye almanız gerekir.
Önemli değişikliklere dair bazı örnekler:
- Yerel derleme kurallarının eklenmesi veya silinmesi
- Yerel kurallarda yapılan önemli değişiklikler
- Yerleşik derleme kuralı semantiklerinde, tek bir kuralın davranışını etkileyen değişiklikler
- Bazel'in kural tanımı API'sinde yapılan değişiklikler
- Bazel'in diğer sistemlere bağlanmak için kullandığı API'lerde yapılan değişiklikler
- Starlark dilinde, semantiklerinde veya API'lerinde yapılan değişiklikler
- Bazel performansı veya bellek kullanımı üzerinde yaygın bir etkisi olabilecek değişiklikler (iyi veya kötü yönde)
- Yaygın olarak kullanılan dahili API'lerde yapılan değişiklikler
- İşaretlerde ve komut satırı arayüzünde yapılan değişiklikler.
Tasarım incelemelerinin nedenleri
Tasarım dokümanı yazarken diğer Bazel geliştiricileriyle koordinasyon sağlayabilir ve Bazel'in çekirdek ekibinden yardım alabilirsiniz. Örneğin, bir öneri BUILD, WORKSPACE veya bzl dosyalarında bulunan herhangi bir işlevi ya da nesneyi eklediğinde, kaldırdığında veya değiştirdiğinde Starlark ekibini incelemeciler olarak ekleyin. Tasarım dokümanları, göndermeden önce incelenir çünkü:
- Bazel çok karmaşık bir sistemdir. Zararsız gibi görünen yerel değişikliklerin küresel ölçekte önemli sonuçları olabilir.
- Ekip, kullanıcılardan birçok özellik isteği alır. Bu tür isteklerin yalnızca teknik fizibilite açısından değil, diğer özellik isteklerine kıyasla önemi açısından da değerlendirilmesi gerekir.
- Bazel özellikleri genellikle çekirdek ekibin dışındaki kişiler tarafından uygulanır. Bu katkıda bulunanların Bazel uzmanlık düzeyleri oldukça farklıdır.
- Bazel ekibinin uzmanlık düzeyleri de farklıdır. Hiçbir ekip üyesi Bazel'in her köşesini tam olarak anlamaz.
- Bazel'de yapılan değişiklikler, geriye dönük uyumluluğu göz önünde bulundurmalı ve bozucu değişikliklerden kaçınmalıdır.
Bazel'in tasarım inceleme politikası, aşağıdakilerin olasılığını en üst düzeye çıkarmaya yardımcı olur:
- tüm özellik isteklerine temel düzeyde inceleme uygulanır.
- Doğru kişiler, işe yaramayabilecek bir uygulamaya yatırım yapmadan önce tasarımlar hakkında fikir verecektir.
Başlamanıza yardımcı olması için Bazel Teklifleri Deposu'ndaki tasarım belgelerine göz atın. Tasarımların geliştirilme aşaması devam ettiğinden uygulama ayrıntıları zaman içinde ve geri bildirimlere göre değişebilir. Yayınlanan tasarım dokümanları, tasarımlar uygulanırken yapılan değişiklikleri değil ilk tasarımı yansıtır. Mevcut Bazel işlevlerinin açıklamaları için her zaman dokümanlara bakın.
Katkıda Bulunan İş Akışı
Katkıda bulunanlar tasarım dokümanı yazabilir, çekme isteği gönderebilir ve önerileri için incelemeci isteğinde bulunabilir.
Tasarım dokümanı yazma
Tüm tasarım belgelerinde aşağıdakileri içeren bir başlık bulunmalıdır:
- yazar
- Son büyük değişikliğin tarihi
- Bir (ve yalnızca bir) baş incelemeci dahil olmak üzere incelemecilerin listesi
- mevcut durum (taslak, inceleniyor, onaylandı, reddedildi, uygulanıyor, uygulandı)
- tartışma dizisinin bağlantısı (duyuru yapıldıktan sonra eklenecektir)
Doküman, dünya genelinde okunabilen bir Google Dokümanı veya Markdown kullanılarak yazılabilir. Markdown / Google Dokümanlar karşılaştırması için aşağıyı okuyun.
Kullanıcılar tarafından görülebilen bir etkisi olan önerilerde, geriye dönük uyumluluk üzerindeki etkiyi (ve gerekirse kullanıma sunma planını) belgeleyen bir bölüm bulunmalıdır.
Alma İsteği Oluşturma
Tasarım dokümanınızı tasarım dizine eklemek için bir alma isteği (PR) oluşturarak paylaşın. Markdown dosyanızı veya bir doküman bağlantısını PR'nize ekleyin.
Mümkünse bir baş incelemeci seçin ve diğer incelemecilerin CC alanına eklenmesini sağlayın. Baş inceleme uzmanı seçmezseniz Bazel geliştiricilerinden biri PR'nize bir baş inceleme uzmanı atar.
PR'nizi oluşturduktan sonra, incelemeciler kod incelemesi sırasında ön yorumlar yapabilir. Örneğin, baş inceleme uzmanı ek inceleme uzmanları önerebilir veya eksik bilgilere dikkat çekebilir. Baş inceleme uzmanı, inceleme sürecinin başlatılabileceğini düşündüğünde PR'yi onaylar. Bu, teklifin mükemmel olduğu veya onaylanacağı anlamına gelmez. Teklifin, tartışmayı başlatmak için yeterli bilgi içerdiği anlamına gelir.
Yeni teklifi duyurma
PR gönderildiğinde bazel-dev grubuna bir duyuru gönderin.
Diğer grupları kopyalayabilirsiniz (örneğin, Bazel son kullanıcılarından geri bildirim almak için bazel-discuss).
İnceleme ekibiyle birlikte çalışma
İlgilenenler teklifinizle ilgili yorum yapabilir. Soruları yanıtlamaya, teklifi açıklamaya ve endişeleri gidermeye çalışın.
Tartışma, duyuru ileti dizisinde yapılmalıdır. Öneri bir Google Dokümanı'ndaysa bunun yerine yorumlar kullanılabilir (anonim yorumlara izin verilir).
Durumu güncelleme
İtiraz tamamlandığında teklifin durumunu güncellemek için yeni bir PR oluşturun. PR'yi aynı baş incelemeciye gönderin ve diğer incelemecilerin CC alanına ekleyin.
Teklifi resmi olarak kabul etmek için baş inceleme uzmanı, diğer inceleme uzmanlarının karara uyduğundan emin olduktan sonra PR'yi onaylar.
İlk duyuru ile teklifin onaylanması arasında en az 1 hafta olmalıdır. Bu sayede kullanıcıların dokümanı okumak ve endişelerini paylaşmak için yeterli zamanı olur.
Uygulama, teklif kabul edilmeden önce başlayabilir (ör. kavram kanıtı veya deneme olarak). Ancak inceleme tamamlanmadan değişikliği gönderemezsiniz.
Baş incelemeci seçme
Baş yorumcu, aşağıdaki özelliklere sahip bir alan uzmanı olmalıdır:
- İlgili alt sistemler hakkında bilgi sahibi
- Objektif ve yapıcı geri bildirim verebilecek
- İnceleme sürecinin tamamında süreci yönetmek için kullanılabilir.
Kişilerde çeşitli ekip etiketleri olup olmadığını kontrol edebilirsiniz.
Markdown ve Google Dokümanlar karşılaştırması
Her ikisi de kabul edildiğinden, size en uygun olana karar verin.
Google Dokümanlar'ı kullanmanın avantajları:
- Kullanmaya başlaması kolay olduğu için beyin fırtınası için etkilidir.
- Ortak çalışmayla düzenleme
- Hızlı iterasyon.
- Düzenleme önermenin kolay yolu.
Markdown dosyalarını kullanmanın avantajları:
- Bağlantı için temiz URL'ler.
- Düzeltmelerin açık kaydı.
- Bağlantıyı yayınlamadan önce erişim haklarını ayarlamayı unutmayın.
- Arama motorlarıyla kolayca aranabilir.
- Gelecekte de kullanılabilir: Basit metin, belirli bir aracın insafına bağlı değildir ve internet bağlantısı gerektirmez.
- Yazar artık mevcut olmasa bile bu bilgileri güncelleyebilirsiniz.
- Bunlar otomatik olarak işlenebilir (geçersiz bağlantıları güncelleyebilir/algılayabilir, yazar listesini getirebilir vb.).
Önce bir Google Dokümanı'nda iterasyon yapmayı, ardından gelecekte kullanmak üzere dokümanı 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 sağlar. Bunu yapmak için Dosya > Kopya oluştur'u tıklayın veya tasarım dokümanı şablonunun bir kopyasını oluşturmak için bu bağlantıyı tıklayın.
Dokümanınızı 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 yorum yapılmasına izin verirseniz Google Hesabı olmasa bile herkes anonim olarak yorum yapabilir.
Markdown'ı kullanma
Belgeler GitHub'da depolanır ve GitHub Markdown biçimi (Spesifikasyon) kullanılır.
Mevcut bir dokümanı güncellemek için PR oluşturun. Önemli değişiklikler, doküman inceleme uzmanları tarafından incelenmelidir. Önemsiz değişiklikler (yazım hataları, biçimlendirme gibi) herkes tarafından onaylanabilir.
İnceleme uzmanı iş akışı
İnceleme uzmanı, tasarım dokümanlarına yorum yapar, dokümanları inceler ve onaylar.
İnceleme uzmanının genel sorumlulukları
Tasarım dokümanlarını incelemek, gerekirse ek bilgi istemek ve inceleme sürecini geçen bir tasarımı onaylamak sizin sorumluluğunuzdadır.
Yeni bir teklif aldığınızda
- Belgeye hızlıca göz atın.
- Kritik bilgiler eksikse veya tasarım projenin hedeflerine uygun değilse yorum yapın.
- Ek incelemeciler önerin.
- İncelemeye hazır olduğunda PR'yi onaylayın.
İnceleme süreci sırasında
- Sorunlu veya açıklama gerektiren sorunlar hakkında tasarımın yazarı ile iletişime geçin.
- Uygun olduğu takdirde, tasarım hakkında bilgi sahibi olması gereken yorumcu olmayan kişilerden yorum almaya davet edin.
- Onay için yazarın hangi yorumları ele alması gerektiğine karar verin.
- Teklifin mevcut durumundan memnun kaldığınızda tartışma mesaj dizisine "LGTM" (Looks Good To Me) yazın.
Tüm tasarım incelemesi istekleri için bu süreci uygulayın. Tasarım dizininde yer almayan ve Bazel'i etkileyen tasarımları onaylamayın.
Baş inceleme uzmanının sorumlulukları
Beklemede olan bir tasarımın uygulanmasıyla ilgili karar verme sorumluluğu size aittir. Bunu yapamıyorsanız uygun bir temsilci belirlemeniz (PR'yi temsilciye yeniden atamanız) veya hatayı başka bir işlem için Basel yöneticisine yeniden atamanız gerekir.
İnceleme süreci sırasında
- Yorum ve tasarım iterasyon sürecinin yapıcı bir şekilde ilerlemesini sağlayın.
- Onay öncesinde, diğer incelemecilerin endişelerinin giderildiğinden emin olun.
Tüm incelemeciler tarafından onaylandıktan sonra
- E-posta listesinde duyurunun üzerinden en az 1 hafta geçtiğinden emin olun.
- PR'nin durumu güncellediğinden emin olun.
- Teklif yazarı tarafından gönderilen PR'yi onaylayın.
Tasarımları reddetme
- PR yazarının PR gönderdiğinden emin olun veya PR yazarına PR gönderin.
- PR, dokümanın durumunu günceller.
- Belgeye, tasarımın mevcut durumunda neden onaylanamadığını açıklayan ve varsa sonraki adımları (ör. "geçersiz varsayımları tekrar inceleyin ve yeniden gönderin") özetleyen bir yorum ekleyin.