Kullanıcıya 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önderebilmeniz için önce bir tasarım belgesi yazmanız ve bu belgeyi inceletmeniz gerekir.
Önemli değişikliklere dair bazı örnekler:
- Yerel derleme kurallarının eklenmesi veya silinmesi
- Yerel kurallarda yapılan, uyumluluğu bozan değişiklikler
- Tek bir kuraldan daha fazlasının davranışını etkileyen yerel derleme kuralı semantiğindeki 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, semantiğinde veya API'lerinde yapılan değişiklikler
- Bazel performansı veya bellek kullanımı üzerinde yaygın bir etkiye sahip 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ştiricilerle koordineli çalışabilir ve Bazel'in temel ekibinden rehberlik alabilirsiniz. Örneğin, bir teklif BUILD, MODULE.bazel veya bzl dosyalarında bulunan herhangi bir işlevi ya da nesneyi eklediğinde, kaldırdığında veya değiştirdiğinde Starlark ekibini inceleyen olarak ekleyin. Tasarım belgeleri, gönderilmeden önce şu nedenlerle incelenir:
- Bazel çok karmaşık bir sistemdir. Görünüşte zararsız olan yerel değişiklikler, küresel olarak önemli sonuçlar doğurabilir.
- Ekip, kullanıcılardan birçok özellik isteği alıyor. Bu isteklerin yalnızca teknik olarak uygulanabilirliği değil, diğer özellik istekleriyle ilgili önemi de değerlendirilmelidir.
- Bazel özellikleri genellikle çekirdek ekibin dışındaki kişiler tarafından uygulanır. Bu katkıda bulunanların Bazel uzmanlığı seviyeleri oldukça farklıdır.
- Bazel ekibinin kendisi de farklı uzmanlık düzeylerine sahiptir. Hiçbir ekip üyesi, Bazel'in her köşesini tam olarak anlamaz.
- Bazel'deki değişiklikler geriye dönük uyumluluğu hesaba katmalı ve uyumluluğu bozacak değişikliklerden kaçınmalıdır.
Bazel'in tasarım inceleme 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 incelenir.
- Doğru kişiler, çalışmayabilecek bir uygulamaya yatırım yapmadan önce tasarımlar hakkında görüşlerini bildirir.
Başlamanıza yardımcı olması için Bazel Proposals Repository'deki tasarım belgelerine göz atın. Tasarımlar geliştirilme aşamasında olduğundan uygulama ayrıntıları zaman içinde ve geri bildirimlere bağlı olarak değişebilir. Yayınlanan tasarım belgeleri, ilk tasarımı yakalar ve tasarımlar uygulanırken devam eden değişiklikleri yakalamaz. Mevcut Bazel işlevlerinin açıklamaları için her zaman dokümanlara bakın.
Katkıda Bulunan İş Akışı
Katkıda bulunan kişi olarak tasarım belgesi yazabilir, çekme istekleri gönderebilir ve teklifiniz için incelemeci isteyebilirsiniz.
Tasarım belgesini yazma
Tüm tasarım belgelerinde aşağıdaki bilgileri içeren bir başlık olmalıdır:
- yazar
- son büyük değişikliğin tarihi
- Bir (ve yalnızca bir) baş incelemeci de dahil olmak üzere incelemecilerin listesi
- Mevcut durum (taslak, inceleniyor, onaylandı, reddedildi, uygulanıyor, uygulandı)
- Tartışma ileti dizisinin bağlantısı (duyurudan sonra eklenecek)
Belge dünyanın her yerinden okunabilen bir Google Dokümanı olarak veya Markdown kullanılarak yazılabilir. Aşağıda Markdown / Google Dokümanlar karşılaştırması hakkında bilgi verilmektedir.
Kullanıcı tarafından görülebilen bir etkisi olan tekliflerde, geriye dönük uyumluluk üzerindeki etkiyi belgeleyen bir bölüm (ve gerekirse kullanıma sunma planı) bulunmalıdır.
Çekme isteği oluşturma
Dokümanı tasarım dizinine eklemek için çekme isteği (PR) oluşturarak tasarım dokümanınızı paylaşın. Markdown dosyanızı veya doküman bağlantınızı PR'nıza ekleyin.
Mümkün olduğunda bir baş incelemeci seçin ve diğer incelemecileri CC'ye ekleyin. Başlıca incelemeci seçmezseniz Bazel bakımcısı, PR'nize bir incelemeci atar.
Çekme isteğinizi oluşturduktan sonra incelemeciler, kod incelemesi sırasında ön yorumlar yapabilir. Örneğin, baş inceleme uzmanı ek inceleme uzmanları önerebilir veya eksik bilgileri belirtebilir. Başlıca incelemeci, inceleme sürecinin başlayabileceğini düşündüğünde PR'yi onaylar. Bu, önerinin mükemmel olduğu veya onaylanacağı anlamına gelmez. Önerinin, tartışmayı başlatmak için yeterli bilgi içerdiği anlamına gelir.
Yeni teklifi duyurma
PR gönderildiğinde bazel-dev adresine duyuru gönder.
Diğer grupları (ör. Bazel son kullanıcılarından geri bildirim almak için bazel-discuss) kopyalayabilirsiniz.
İncelemecilerle birlikte yineleme yapma
İlgilenen herkes önerinize yorum yapabilir. Soruları yanıtlamaya, teklifi netleştirmeye ve endişeleri gidermeye çalışın.
Tartışma, duyuru ileti dizisinde yapılmalıdır. Öneri bir Google Dokümanı'ndaysa yorumlar kullanılabilir (Anonim yorumlara izin verildiğini unutmayın).
Durumu güncelleme
Tekrar tamamlandığında teklifin durumunu güncellemek için yeni bir PR oluşturun. PR'yi aynı baş inceleme uzmanına gönderin ve diğer inceleme uzmanlarını CC'ye ekleyin.
Teklifi resmen kabul etmek için başlık incelemeci, diğer incelemecilerin karara katıldığından 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 belgeyi okumak ve endişelerini paylaşmak için yeterli zamanı olur.
Uygulama, teklif kabul edilmeden önce başlayabilir. Örneğin, kavram kanıtı veya deneme olarak. Ancak inceleme tamamlanmadan değişikliği gönderemezsiniz.
Başlıca incelemeciyi seçme
Baş yorumcu, aşağıdaki özelliklere sahip bir alan uzmanı olmalıdır:
- İlgili alt sistemler hakkında bilgi sahibi olmalıdır.
- Tarafsız ve yapıcı geri bildirimler verebilen
- Süreci yönetmek için tüm inceleme dönemi boyunca kullanılabilir.
Çeşitli ekip etiketleri için kişileri kontrol etmeyi deneyin.
Markdown ve Google Dokümanlar
Her ikisi de kabul edildiğinden size en uygun olanına karar verin.
Google Dokümanlar'ı kullanmanın avantajları:
- Kullanmaya başlamak kolay olduğundan beyin fırtınası için etkilidir.
- Ortak çalışmaya dayalı düzenleme
- Hızlı yineleme.
- Kolayca düzenleme önerebilirsiniz.
Markdown dosyalarını kullanmanın avantajları:
- Bağlantı oluşturmak için temiz URL'ler.
- Düzeltmelerin açık kaydı.
- Bağlantıyı herkese açık hale getirmeden önce erişim haklarını ayarlamayı unutmazsınız.
- Arama motorlarıyla kolayca aranabilir.
- Geleceğe hazır: Düz metin, belirli bir aracın insafına kalmaz ve internet bağlantısı gerektirmez.
- Yazar artık mevcut olmasa bile bu tür yayınlar güncellenebilir.
- Otomatik olarak işlenebilirler (güncelleme/çalışmayan bağlantıları algılama, yazar listesini getirme vb.).
Önce bir Google Dokümanı üzerinde yineleme yapıp daha sonra bunu gelecekte kullanmak üzere Markdown'a dönüştürebilirsiniz.
Google Dokümanlar'ı kullanma
Tutarlılık için Bazel tasarım dokümanı şablonunu kullanın. Gerekli başlığı içerir ve diğer Bazel ile ilgili dokümanlarla görsel tutarlılık oluşturur. Bunu yapmak için Dosya > Kopya oluştur'u tıklayın veya bu bağlantıyı tıklayarak tasarım dokümanı şablonunun kopyasını oluşturun.
Dokümanınızın herkes tarafından okunabilmesini sağlamak 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ı olmayanlar da dahil olmak üzere herkes anonim olarak yorum yapabilir.
Markdown'ı kullanma
Dokümanlar GitHub'da saklanır ve GitHub Markdown'u (Şartname) kullanılır.
Mevcut bir dokümanı güncellemek için bir PR oluşturun. Önemli değişiklikler, doküman inceleyicileri tarafından incelenmelidir. Önemsiz değişiklikler (ör. yazım hataları, biçimlendirme) herkes tarafından onaylanabilir.
İnceleme iş akışı
Bir incelemeci, tasarım belgelerini yorumlar, inceler ve onaylar.
Genel inceleme uzmanı sorumlulukları
Tasarım belgelerini 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.
- Önemli bilgiler eksikse veya tasarım projenin hedeflerine uygun değilse yorum yapın.
- Ek incelemeciler önerme
- İncelemeye hazır olduğunda PR'yi onaylayın.
İnceleme süreci sırasında
- Sorunlu olan veya açıklama gerektiren konular hakkında tasarım yazarıyla diyalog kurun.
- Uygun olduğu takdirde, tasarım hakkında bilgi sahibi olması gereken, yorumcu olmayan kişilerden yorum isteyin.
- Yazarın onay öncesinde hangi yorumları ele alması gerektiğini belirleyin.
- Teklifin mevcut durumundan memnunsanız tartışma iş parçacığına "LGTM" (Looks Good To Me) yazın.
Tüm tasarım inceleme istekleri için bu süreci uygulayın. Tasarım dizininde yer almayan ve Bazel'i etkileyen tasarımları onaylamayın.
Baş incelemecinin sorumlulukları
Bekleyen bir tasarımın uygulanıp uygulanmayacağına karar vermek sizin sorumluluğunuzdadır. Bunu yapamıyorsanız uygun bir temsilci belirlemeli (PR'yi temsilciye yeniden atamalı) veya daha fazla işlem için hatayı bir Bazel yöneticisine yeniden atamalısınız.
İnceleme süreci sırasında
- Yorum ve tasarım yineleme sürecinin yapıcı bir şekilde ilerlemesini sağlayın.
- Onaydan önce, diğer inceleme uzmanlarının endişelerinin giderildiğinden emin olun.
Tüm incelemeciler onayladıktan sonra
- Posta listesindeki duyurunun üzerinden en az 1 hafta geçtiğinden emin olun.
- Çekme isteğinin durumu güncellediğinden emin olun.
- Teklif yazarının gönderdiği çekme isteğini onaylayın.
Tasarımları reddetme
- PR yazarının PR gönderdiğinden emin olun veya ona PR gönderin.
- PR, belgenin durumunu günceller.
- Tasarımın neden mevcut haliyle onaylanamayacağını açıklayan ve varsa sonraki adımları (ör. "Geçersiz varsayımları yeniden gözden geçirin ve yeniden gönderin") özetleyen bir yorum ekleyin.