Kullanıcıya yönelik bir özellik eklemeyi, değiştirmeyi veya kaldırmayı ya da Bazel'da önemli bir mimari değişiklik yapmayı planlıyorsanız değişikliği gönderebilmeniz için bir tasarım dokümanı incelemeniz ve incelemesini sağlamanız gerekir.
Aşağıda önemli değişikliklere ilişkin bazı örnekler verilmiştir:
- Yerel derleme kuralları ekleme veya silme
- Yerel kurallarda kırık değişiklikler
- Tek bir kuraldan daha fazlasının davranışını etkileyen yerel derleme kuralı semantiğinde yapılan değişiklikler
- Bazel'ın 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, semantiği veya API'lerinde yapılan değişiklikler
- Bazel performansını veya bellek kullanımını yaygın şekilde etkileyebilecek değişiklikler (daha iyi veya daha kötü için)
- 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
Bir tasarım dokümanı yazarken diğer Bazel geliştiricileriyle koordinasyon sağlayabilir ve Bazel'ın çekirdek ekibinden yardım isteyebilirsiniz. Örneğin bir teklif; BUILD, WORKSPACE veya bzl dosyalarında bulunan işlevleri ya da nesneleri ekler, kaldırır veya değiştirirse Starlark ekibini incelemeci olarak ekleyin. Tasarım dokümanları göndermeden önce incelenir çünkü:
- Bazel çok karmaşık bir sistemdir. Görünüşte masum görünen yerel değişikliklerin küresel olarak önemli 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 de önemlendirilmesi gerekir.
- Bazel özellikleri, ana ekibin dışındaki kişiler tarafından da sık sık uygulanır. Bu gibi katılımcıların Bazel uzmanlık düzeyleri büyük ölçüde değişiklik gösterir.
- Bazel ekibinin farklı uzmanlık seviyeleri vardır. Tek bir ekip üyesi bile Bazel'ın her köşesini çok iyi anlamamıştır.
- Bazel'da yapılan değişiklikler geriye dönük uyumluluğu hesaba katmalı ve değişikliklerden zarar görmemelidir.
Bazel'ın tasarım inceleme politikası, aşağıdaki durumlarla karşılaşma olasılığını en üst düzeye çıkarmaya yardımcı olur:
- Tüm özellik istekleri temel düzeyde incelenir.
- işe yaramayabilecek bir uygulamaya yatırım yapmadan önce tasarımlar üzerinde çalışacaktır.
Başlamanıza yardımcı olması için Bazel Teklif Deposu'ndaki tasarım dokümanlarına göz atın. Tasarımlar devam ettiğinden uygulama ayrıntıları zaman içinde ve geri bildirimlerle değişebilir. Yayınlanan tasarım dokümanları ilk tasarımla ilgili olduğundan, tasarımlar uygulanırken devam eden değişiklikler gerçekleşmez. Mevcut Bazel işlevlerinin açıklamaları için her zaman ilgili belgelere gidin.
Katkıda Bulunan İş Akışı
Katkıda bulunan olarak bir tasarım dokümanı yazabilir, pull istekleri gönderebilir ve teklifiniz için incelemeci isteyebilirsiniz.
Tasarım dokümanını yazma
Tüm tasarım dokümanlarının bulunduğu bir başlık olmalıdır:
- author
- son büyük değişiklik tarihi
- Bir (ve sadece bir) potansiyel müşteri inceleme uzmanı dahil olmak üzere yorumcuların listesi
- mevcut durum (taslak, inceleniyor, onaylandı, reddedildi, uygulanıyor, uygulanıyor
- tartışma ileti dizisine bağlantı (duyurudan sonra eklenecek)
Belge, dünya çapında okunabilir bir Google Dokümanı olarak veya Markdown kullanılarak yazılabilir. Markdown / Google Dokümanlar karşılaştırması için aşağıdaki bölüme bakın.
Kullanıcı tarafından görülebilen etkisi olan tekliflerde, geriye dönük uyumluluk üzerindeki etkiyi (ve gerekirse bir kullanıma sunma planını) belgeleyen bir bölüm bulunmalıdır.
Pull İsteği Oluşturma
Dokümanı tasarım dizinine eklemek için bir pull isteği (PR) oluşturarak tasarım belgenizi paylaşın. PR'nize Markdown dosyanızı veya bir doküman bağlantısı ekleyin.
Mümkün olduğunda bir potansiyel müşteri inceleme uzmanı seçin ve diğer yorumcuları cc'ye ekleyin. Hizmet talebi inceleme uzmanı seçmezseniz Bazel'ın bir bakıcısı, halkla ilişkiler departmanınıza atar.
PR'nizi oluşturduktan sonra incelemeciler kod incelemesi sırasında ön yorumlar yapabilir. Örneğin, potansiyel müşteri incelemeci ekstra incelemeciler önerebilir veya eksik bilgileri gösterebilir. Potansiyel müşteri inceleme uzmanı, inceleme sürecinin başlayacağına inandığında Halkla İlişkileri onaylar. Bu, teklifin mükemmel olduğu veya onaylanacağı anlamına gelmez; teklifin, tartışmayı başlatmak için yeterli bilgiyi içerdiği anlamına gelir.
Yeni teklifi duyurma
Halkla ilişkiler raporu gönderildiğinde bazel-dev'e bir duyuru gönderin.
Diğer grupları kopyalayabilirsiniz (örneğin, Bazel son kullanıcılarından geri bildirim almak için bazel-Tartışması).
İncelemecilerle denemeler yapın
İlgilenen herkes teklifinize yorum yapabilir. Soruları yanıtlamaya, teklifi netleştirmeye ve endişeleri çözmeye çalışın.
Tartışma, duyuru dizisinde gerçekleşmelidir. Teklif bir Google Dokümanı'ndaysa 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'yı aynı potansiyel müşteri incelemeciye gönderin ve diğer incelemecileri cc'ye ekleyin.
Potansiyel müşteri incelemecisi, teklifi resmi olarak kabul etmek için diğer incelemecilerin karara katıldığından emin olduktan sonra Halkla İlişkileri onaylar.
İlk duyuru ile bir teklifin onaylanması arasında en az 1 hafta olmalıdır. Böylece kullanıcılar dokümanı okumak ve endişelerini paylaşmak için yeterli zamana sahip olur.
Uygulama, teklifin kabul edilmesinden önce (ör. kavram kanıtlama veya deneme) başlayabilir. Ancak, inceleme tamamlanmadan önce değişikliği gönderemezsiniz.
Hizmet talebi inceleme uzmanı seçme
Potansiyel müşteri incelemecisi, aşağıdaki nitelikleri taşıyan bir alan uzmanı olmalıdır:
- Alakalı alt sistemler hakkında bilgi sahibidir
- Amaç ve yapıcı geri bildirimde bulunabilme
- Sürecin yürütülmesi için tüm inceleme süresi boyunca kullanılabilir
Kişileri çeşitli ekip etiketleri için kontrol edebilirsiniz.
Markdown - 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şlamak kolay olduğu için 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ı oluşturmak için URL'leri temizleyin.
- Düzeltmelerin açıkça kaydedilmesi.
- Bağlantıları duyurmadan önce erişim haklarını ayarlamayı unutmayın.
- Arama motorları ile kolayca arama yapabilirsiniz.
- Geleceğe hazır: Düz metin belirli bir aracın merhabi değildir ve internet bağlantısı gerektirmez.
- Yazar artık mevcut olmasa bile bunları güncelleyebilirsiniz.
- Otomatik olarak işlenebilir (ölü bağlantıları güncelleme/algılama, yazarların listesini getirme vb.).
Önce bir Google Dokümanı'nı iterasyon yapıp daha sonra bunu Yenilik için Markdown'a dönüştürebilirsiniz.
Google Dokümanlar'ı kullanma
Tutarlılık için Bazel tasarım dokümanı şablonunu kullanın. Gerekli üstbilgiyi 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 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... 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 (Spesifikasyon) kullanır.
Mevcut bir dokümanı güncellemek için PR oluşturun. Önemli değişiklikler, doküman inceleyiciler tarafından incelenmelidir. Önemli değişiklikler (yazım hataları, biçimlendirme gibi) herkes tarafından onaylanabilir.
Yorumcu iş akışı
İnceleme ekibi, tasarım belgelerini inceler, onaylar ve onaylar.
Yorumcunun genel sorumlulukları
Tasarım belgelerini incelemek, gerekirse daha fazla bilgi istemek ve inceleme sürecinden 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, proje hedeflerine uymuyorsa yorum yapın.
- Ek incelemeciler önerin.
- İncelenmeye hazır olduğunda PR'yi onaylayın.
İnceleme sürecinde
- Sorunlu veya açıklığa kavuşturulması gereken sorunlar için tasarım yazarıyla diyalog kurun.
- Uygunsa tasarımın farkında olan incelemeci olmayan kullanıcıların yorumlarını davet edin.
- Onay için ön koşul olarak hangi yorumların yazar tarafından ele alınacağına karar verin.
- Teklifin geçerli durumundan memnun olduğunuzda tartışma 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'ı etkileyen tasarımları onaylamayın.
Potansiyel müşteri inceleme uzmanının sorumlulukları
Beklemedeki bir tasarımın uygulanmasına ilişkin karar verme kararını vermek sizin sorumluluğunuzdadır. Bunu yapamıyorsanız uygun bir yetki verilmiş kullanıcı tanımlamanız (PR'yi yetki verilmiş kullanıcıya yeniden atamanız) veya hatayı daha iyi bir deneyime sahip olması için Bazel yöneticisine yeniden atamanız gerekir.
İnceleme sürecinde
- Yorum ve tasarım yineleme işleminin 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.
- 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 bir PR gönderdiğine emin olun veya bir PR gönderin.
- Halkla ilişkiler, dokümanın durumunu günceller.
- Dokümana, mevcut haliyle tasarımın neden onaylanamadığını ve varsa sonraki adımları ana hatlarıyla açıklayan bir yorum ekleyin ("Geçersiz varsayımları yeniden ziyaret edin ve yeniden gönderin" gibi).