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 örnek olarak şunlar verilebilir:
- Yerel derleme kurallarının eklenmesi veya silinmesi
- Yerel kurallarda yapılan değişiklikler
- Yerel derleme kuralı anlamında yapılan ve tek bir kurala göre
- 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 teklif eklendiğinde, BUILD, WORKSPACE veya bzl dosyalarını incelemek için Starlark ekibini incelemeci 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 ekip dışındaki kişiler tarafından uygulanır; bu tür katkıda bulunanlar çok çeşitli Bazel uzmanlık düzeylerine sahiptir.
- Bazel ekibinin farklı uzmanlık seviyeleri vardır; ekipte tek bir üye yok kavradığını fark ettim.
- 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 incelemesi politikası, aşağıdaki olasılıkların en üst düzeye çıkarılmasına yardımcı olur:
- Tüm özellik istekleri, temel düzeyde incelemeden geçer.
- biz tasarıma yatırım yapmadan önce doğru insanların ve bu yöntemin işe yaramamasını sağlayabilirsiniz.
Başlamanıza yardımcı olması için Bazel Teklifleri Deposu'ndaki tasarım belgelerine göz atın. Tasarımlar geliştirme aşamasında olduğundan uygulama ayrıntıları zaman içinde ve geri bildirimler doğrultusunda değişebilir. Yayınlanan tasarım belgeleri ilk tasarımı, değil. Her zaman şuraya gidin: dokümanlarına göz atabilirsiniz.
Katkıda Bulunan İş Akışı
Katkıda bulunan olarak, bir tasarım belgesi yazabilir, Teklifiniz için inceleme uzmanları isteyebilirsiniz.
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, uygulanıyor)
- tartışma mesaj 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. Aşağıdakileri okuyun: Markdown / Google Dokümanlar karşılaştırması.
Kullanıcı tarafından görülebilen etkiye sahip tekliflerde, geriye dönük uyumluluk üzerindeki etkisi (ve gerekirse bir kullanıma sunma planı).
Çekme İ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ün olduğunda bir potansiyel müşteri inceleme uzmanı seçin. ve diğer inceleyicileri cc'ye ekleyin. Baş inceleme uzmanı seçmezseniz Bazel bakım uzmanı, PR'nize bir baş inceleme uzmanı atar.
PR'nizi oluşturduktan sonra, inceleme uzmanları süreç boyunca kod incelemesi. Örneğin, potansiyel müşteri inceleme uzmanı ekstra inceleme uzmanları önerebilir veya eksik bilgilere dikkat edin. 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 duyurun
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 uzmanlarıyla birlikte denemeler yapın
İlgilenen herkes teklifinize yorum yapabilir. Soruları yanıtlamaya, teklifi açıklamaya ve endişeleri gidermeye ç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 verilir).
Durumu güncelleme
Yineleme olduğunda, teklifin durumunu güncellemek için yeni bir PR oluşturun belirir. PR'yi aynı baş incelemeciye gönderin ve diğer incelemecilerin CC alanına ekleyin.
Baş inceleme uzmanı, teklifi resmi olarak kabul etmek için diğer incelemecilerin karara katılmalarını sağlamak.
İlk duyuru ile teklifin onaylanması arasında en az 1 hafta olmalıdır. Bu, kullanıcıların belgeyi okumak için yeterli zamanı ve endişelerini paylaşmalarını isteyebilirsiniz.
Uygulama, teklif kabul edilmeden önce başlayabilir. Örneğin, Kavram kanıtlama veya deney. Ancak inceleme tamamlanmadan değişikliği gönderemezsiniz.
Baş incelemeci seçme
Potansiyel müşteri inceleyici, 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.
Çeşitli ekiplerin kişilerine göz atabilirsiniz. etiketleri kullanın.
Markdown ve Google Dokümanlar karşılaştırması
Her ikisi de kabul edildiğinden sizin için en uygun olana karar verin.
Google Dokümanlar'ı kullanmanın avantajları:
- Başlarken kolay olduğundan beyin fırtınası için etkilidir.
- Ortak çalışmaya dayalı 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.
- Geleceğe karşı hazırlıklı: Düz metin herhangi bir aracın izni değildir ve internet bağlantısı gerektirmez.
- Yazar artık ortada olmasa bile bu sayfaları güncellemek mümkündür.
- Otomatik olarak işlenebilirler (ölü bağlantıları güncelleme/algılama, getirme ve yazar listesi vb.) girin.
Önce bir Google Dokümanı'nı yinelemeyi, sonra da Geleceğin dönemleri için Markdown.
Google Dokümanlar'ı kullanma
Tutarlılık için Bazel tasarım dokümanı şablonunu kullanın. Gerekli başlığı içerir ve görsel tutarlı olduğunu gösteren belgelere göz atın. Bunun için Dosya > Kopyasını oluştur veya bu bağlantıyı tıklayarak tasarım dokümanının bir kopyasını oluşturun şablonunu 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 yorumlara izin verirseniz Google hesabı olmasa bile herkes anonim olarak yorum yapabilir.
Markdown'ı kullanma
Dokümanlar GitHub'da depolanır ve Markdown'ın GitHub aroması (Spesifikasyon).
Mevcut bir dokümanı güncellemek için PR oluşturun. Önemli değişiklikler ve belge incelemecileri tarafından incelenir. Önemsiz değişiklikler (ör. yazım hataları, biçimlendirme) herkes tarafından onaylanabilir.
İnceleme uzmanı iş akışı
İnceleme uzmanı, tasarım dokümanlarına yorum yapar, dokümanları inceler ve onaylar.
İncelemecilerin 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 uymuyorsa yorum yapın netleştirmeye yardımcı olur.
- Ek incelemeciler önerin.
- İncelemeye hazır olduğunda PR'yi onaylayın.
İnceleme süreci sırasında
- Sorunlu sorunlar hakkında tasarımın yazarıyla diyalog kurun veya açıklama gerektirmeyebilir.
- 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 inceleme istekleri için bu süreci izleyin. Tasarım dizininde yer almayan ve Bazel'i etkileyen tasarımları onaylamayın.
Lider incelemecinin sorumlulukları
Beklemede olan bir tasarımın uygulanmasıyla ilgili karar verme sorumluluğu size aittir. Bunu yapamıyorsanız bir uygun bir delege edin (PR'yi yetki verilen kullanıcıya yeniden atayın) veya hatayı İşleri halletmek için Bazel müdürüyüm.
İnceleme süreci sırasında
- Yorum ve tasarım yineleme sürecinin ilerlediğinden emin olun yapın.
- Onay vermeden önce, diğer incelemecilerin endişelerinin olduğundan emin olun. çözüme ulaştırıldı.
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 reddediliyor
- PR yazarının PR gönderdiğinden emin olun veya PR yazarına PR gönderin.
- PR, dokümanın durumunu günceller.
- Dokümana, tasarımın neden onaylanamadığını açıklayan bir yorum ekleyin. ve varsa sonraki adımların özetlenmesi (örneğin, "Geçersiz web sitesini tekrar ziyaret varsayımları ve yeniden gönderme).