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 dokümanı yazmalı ve incelenmesi gerekir.
Önemli değişikliklere ilişkin bazı örnekleri aşağıda bulabilirsiniz:
- Yerel derleme kuralları ekleme veya silme
- Yerel kurallarda yapılan değişiklikler
- Yerel derleme kuralı anlamında yapılan ve tek bir kuraldan daha fazla kuralın davranışını etkileyen değişiklikler
- Bazel 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 dili, anlamı veya API'lerinde yapılan değişiklikler
- Bazel performansını veya bellek kullanımını kapsamlı şekilde etkileyebilecek değişiklikler (iyi veya kötü amaçla)
- Yaygın olarak kullanılan dahili API'lerde yapılan değişiklikler
- İşaretler ve komut satırı arayüzünde yapılan değişiklikler.
Tasarım incelemelerinin nedenleri
Tasarım belgesi yazarken diğer Bazel geliştiricileriyle koordine olabilir ve Bazel'ın çekirdek ekibinden yardım isteyebilirsiniz. Örneğin, bir teklif BUILD, WORKSPACE veya bzl dosyalarında bulunan herhangi bir işlev veya nesneyi eklediğinde, kaldırdığında ya da değiştirdiğinde, Starlark ekibini incelemeci olarak ekleyin. Tasarım dokümanları gönderilmeden önce incelenir, çünkü:
- Bazel çok karmaşık bir sistemdir. Görünüşe göre zararsız olan yerel değişiklikler, önemli küresel sonuçlar doğurabilir.
- Ekip, kullanıcılardan çok sayıda özellik talebi alır. Bu tür isteklerin yalnızca teknik uygulanabilirlik açısından değil, aynı zamanda diğer özellik istekleri açısından önemi açısından da değerlendirilmesi gerekir.
- Bazel özellikleri sıklıkla çekirdek ekip dışındaki kişiler tarafından uygulanır. Bu tür katkıda bulunanların Bazel uzmanlık seviyeleri çok farklıdır.
- Bazel ekibinin farklı uzmanlık seviyeleri vardır. Hiçbir ekip üyesi Bazel'in her köşesini kavrayabilir.
- Bazel'de yapılan değişiklikler, geriye dönük uyumluluğu hesaba katmalı ve değişikliklerin bozulmasını önlemelidir.
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.
- çalışmayabilecek bir uygulamaya yatırım yapmadan önce doğru insanlar tasarım üzerine fikir verecektir.
Başlamanıza yardımcı olması için Bazel Teklifleri Deposu'ndaki tasarım belgelerine göz atın. Tasarımlar devam ettiği için uygulama ayrıntıları zamanla ve geri bildirimlerle değişebilir. Yayınlanan tasarım belgeleri ilk tasarımı yansıtır, tasarımlar uygulanırken devam eden değişiklikleri yazmaz. Mevcut Bazel işlevinin açıklamaları için her zaman belgelere gidin.
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 dokümanlarının şunları içeren bir başlığı olmalıdır:
- yazar
- son büyük değişikliğin tarihi
- Bir (ve yalnızca bir) potansiyel müşteri incelemeci dahil olmak üzere incelemecilerin listesi
- mevcut durum (taslak, inceleniyor, onaylandı, reddedildi, uygulanıyor, uygulandı)
- tartışma dizisine bağlantı (duyurudan sonra eklenecek)
Doküman, herkesin okuyabileceği bir Google Dokümanı olarak veya Markdown kullanılarak yazılabilir. Markdown / Google Dokümanlar'ın karşılaştırması için aşağıdaki bölümü inceleyin.
Kullanıcı tarafından görülebilen bir etkiye sahip tekliflerde, geriye dönük uyumluluk üzerindeki etkiyi belgeleyen bir bölüm (ve gerekirse bir kullanıma sunma planı) bulunmalıdır.
Çekme İsteği Oluşturma
Dokümanı tasarım dizinine eklemek için pull isteği (PR) oluşturarak tasarım belgenizi paylaşın. Markdown dosyanızı veya PR'nize bir doküman bağlantısı ekleyin.
Mümkün olduğunda bir potansiyel müşteri yorumcusu seçin ve diğer incelemecileri cc'ye ekleyin. Potansiyel müşteri yorumcusu seçmezseniz bir Bazel şefi, halkla ilişkiler departmanınıza bir temsilci atar.
PR'nizi oluşturmanızın ardından, incelemeciler kod incelemesi sırasında ön yorumlar yapabilir. Örneğin, potansiyel müşteri inceleyici fazladan incelemeciler önerebilir veya eksik bilgileri işaretleyebilir. Baş inceleme uzmanı, inceleme sürecinin başlayabileceğini düşündüğünde halkla ilişkiler (PR) departmanını onaylar. Bu, teklifin mükemmel olduğu veya onaylanacağı anlamına gelmez. Yalnızca teklifin tartışmayı başlatmak için yeterli bilgiye sahip olduğu anlamına gelir.
Yeni teklifi duyurun
halkla ilişkiler belgesi gönderildiğinde bazel-dev'e bir duyuru gönderin.
Diğer grupları (örneğin, bazel-caption) kopyalayabilirsiniz. Böylece Bazel son kullanıcılarından geri bildirim alabilirsiniz.
İnceleme uzmanlarıyla birlikte denemeler yapı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 gerçekleşmelidir. Teklif bir Google Dokümanı'ndaysa yorumlar yerine yorumlar kullanılabilir (Anonim yorumlara izin verildiğini unutmayın).
Durumu güncelleyin
Yineleme tamamlandığında teklifin durumunu güncellemek için yeni bir PR oluşturun. PR'yi aynı potansiyel müşteri inceleyiciye göndermek ve diğer incelemecileri cc'ye eklemek.
Baş incelemeci, teklifi resmi olarak kabul etmek için diğer incelemecilerin karar üzerinde hemfikir olmasını sağladıktan sonra PR'yi onaylar.
İlk duyuru ile teklifin onaylanması arasında en az 1 hafta olmalıdır. Bu, kullanıcıların dokümanı 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 olarak) başlatılabilir. Ancak inceleme tamamlanmadan değişikliği gönderemezsiniz.
Potansiyel müşteri inceleme uzmanı seçme
Potansiyel müşteri inceleyici, aşağıdaki özelliklere sahip bir alan uzmanı olmalıdır:
- Alakalı alt sistemler hakkında bilgi sahibi
- Yapıcı geri bildirim sağlama amacı ve becerisi
- Sürecin yönetilmesi için inceleme süresinin tamamı boyunca kullanılabilir.
Çeşitli ekip etiketleri için kişileri kontrol etmeyi düşünün.
Markdown ve Google Dokümanlar
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ı verilen URL'leri temizleyin.
- Düzeltmelerin açık kaydı.
- Bir bağlantıyı herkese açık olarak yayınlamadan önce erişim haklarını ayarlamayı unutmayın.
- Arama motorlarıyla kolayca aranabilir.
- Geleceğe hazır: Düz metin metinlerin kullanılmasına izin verilmez ve herhangi bir internet bağlantısı gerekmez.
- 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, yazar listesini getirme vb.).
Önce bir Google Dokümanı'nı yinelemeyi, sonra da daha sonra geliştirmek üzere 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 belgelerle görsel tutarlılık sağlar. Bunu yapmak için Dosya > Kopya oluştur'u tıklayın veya bu bağlantıyı tıklayarak tasarım dokümanı şablonunun bir kopyasını oluşturun.
Dokümanınızı herkes tarafından okunabilir hale getirmek için Paylaş > Gelişmiş > Değiştir... seçeneğini tıklayın ve "Açık - Bağlantıya sahip olan herkes" seçeneğini belirleyin. 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 çeşidini (Specification) kullanır.
Mevcut bir dokümanı güncellemek için PR oluşturun. Önemli değişiklikler, belge incelemecileri tarafından incelenmelidir. Önemsiz değişiklikler (yazım hataları, biçimlendirme gibi) herkes tarafından onaylanabilir.
İnceleme uzmanı iş akışı
İncelemeyi yapan kişi, tasarım dokümanlarını inceler, onaylar ve onaylar.
İncelemecilerin genel sorumlulukları
Tasarım belgelerini incelemek, gerekirse ek bilgi istemek ve inceleme sürecinden geçen 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ın projenin hedeflerine uygun olmaması durumunda yorum yapın.
- Başka inceleme uzmanları önerin.
- İncelenmeye hazır olduğunda halkla ilişkiler belgesini onaylayın.
İnceleme süreci sırasında
- Sorunlu veya açıklama gerektiren sorunlar hakkında tasarımın yazarıyla diyalog kurun.
- Uygun durumlarda, tasarımdan haberdar olması gereken incelemeci olmayanların yorumlarını davet edin.
- Onay almak için ön koşul 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 inceleme istekleri için bu süreci izleyin. Tasarım dizininde olmayan Bazel'i etkileyen tasarımları onaylamayın.
Lider incelemecinin sorumlulukları
Bekleyen bir tasarımın uygulanması konusunda karar vermekten sorumlu olursunuz. Bunu yapamıyorsanız uygun bir temsilci belirlemeli (PR'yi yetki verilen kullanıcıya yeniden atamalı) veya daha sonraki işlemleri yapması 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 ilerlediğinden emin olun.
- Onaydan önce, diğer incelemecilerin endişelerinin giderildiğinden emin olun.
Tüm inceleme uzmanlarının onayından sonra
- Posta listesindeki duyurunun üzerinden en az 1 hafta geçtiğinden emin olun.
- PR'nin durumu güncellediğinden emin olun.
- Teklifi yazan kişinin gönderdiği tanıtım e-postasını onaylayın.
Tasarımlar reddediliyor
- Halkla ilişkiler yazarının halkla ilişkiler belgesi gönderdiğinden emin olun veya tanıtım yazısı gönderin.
- PR, dokümanın durumunu günceller.
- Dokümana, tasarımın mevcut haliyle neden onaylanamayacağını açıklayan ve varsa sonraki adımların ana hatlarını açıklayan bir yorum ekleyin (örneğin, "geçersiz varsayımları yeniden gözden geçirin ve yeniden gönderin").