Kullanıcılara yönelik bir özellik eklemeyi, değiştirmeyi veya kaldırmayı ya da yeni bir özellik önemli bir mimari değişikliği varsa bir tasarım oluşturmalısınız. değişikliği göndermeden önce dokümanı incelemeye göndermeniz 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 kurala göre
- 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ı veya belleği üzerinde kapsamlı bir etkisi olabilecek değişiklikler kullanım (iyi veya kötüsü)
- 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 işbirliği yapabilirsiniz. Bazel'ın çekirdek ekibinden rehberlik almaya devam edebiliyorlar. Ö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önderilmeden önce incelenir, çünkü:
- Bazel çok karmaşık bir sistemdir. yerel olarak yapılan değişiklikler önemli küresel sonuçları olabilir.
- Ekip, kullanıcılardan birçok özellik talebi alır. bu tür taleplerin yalnızca teknik uygulanabilirlik açısından değil, aynı zamanda başka özellik istekleri var.
- 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 hesaba katmalı ve bozulmalarını önlemelidir. anlamına gelir.
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. Tasarımlar devam ettiği için uygulama ayrıntıları zamanla değişebilir ve geri bildirim yoluyla. 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 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) dahil olmak üzere incelemeci listesi potansiyel müşteri inceleme uzmanı
- mevcut durum (taslak, inceleniyor, onaylandı, reddedildi, uygulanıyor, uygulanıyor)
- tartışma dizisine bağlantı (duyurudan sonra eklenecek)
Doküman, herkesin okuyabileceği bir Google Dokümanı olarak yazılabilir veya Markdown kullanarak. 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ı eklemek için bir pull isteği (PR) oluşturarak paylaşın tasarım endeksi. Ekle Markdown dosyanız veya PR'nize bir doküman bağlantısı ekleyin.
Mümkün olduğunda bir potansiyel müşteri inceleme uzmanı seçin. ve diğer inceleyicileri cc'ye ekleyin. Potansiyel müşteri yorumcusunu seçmezseniz bir Bazel sorumlu bir kişi size bir görev 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. İnceleme uzmanı, müşteriden gelen inceleme sürecinin başlayabileceğine inanıyor. Bu, teklifin mükemmel olduğu anlamına gelmez. veya onaylanacak olması; bu da teklifin projenin tamamlanması için tartışmayı başlatın.
Yeni teklifi duyurun
Şu kullanıcılara duyuru gönder: bazel-dev basın.
Diğer grupları (örneğin, bazel-tartı, (Bazel son kullanıcılarından geri bildirim almak için).
İnceleme uzmanlarıyla birlikte denemeler yapın
İlgilenen herkes teklifinize yorum yapabilir. Soruları yanıtlamaya çalışın, netleştirmeli ve endişeleri gidermelidir.
Tartışma, duyuru ileti dizisinde gerçekleşmelidir. Teklif Google Dokümanı'nda, yorumlar yerine yorumlar kullanılabilir (Anonim yorumların izin verilir).
Durumu güncelleyin
Yineleme olduğunda, teklifin durumunu güncellemek için yeni bir PR oluşturun belirir. PR'yi aynı potansiyel müşteri inceleyiciye göndermek ve diğer incelemecileri cc'ye eklemek.
Baş inceleme uzmanı, teklifi resmi olarak kabul etmek için diğer incelemecilerin karara katılmalarını sağlamak.
İlk duyuru ile onayının verilmesi arasında en az 1 hafta olmalıdır. teklife dönüşebilir. 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 değişikliği gönderemezsiniz kontrol edin.
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 ekiplerin kişilerine göz atabilirsiniz. etiketleri kullanı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 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ın herkes tarafından okunabilmesi için şunu tıklayın: Paylaş > Gelişmiş > Change... 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ışı
İncelemeyi yapan kişi, tasarım dokümanlarını inceler, onaylar ve onaylar.
İncelemecilerin genel sorumlulukları
Tasarım belgelerini incelemek ve ek belgeler talep etmek, ve inceleme sürecinden geçen bir tasarımı onaylamalıdı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.
- Başka inceleme uzmanları önerin.
- İncelenmeye hazır olduğunda halkla ilişkiler belgesini onaylayın.
İnceleme süreci sırasında
- Sorunlu sorunlar hakkında tasarımın yazarıyla diyalog kurun veya açıklama gerektirmeyebilir.
- Uygunsa incelemeci olmayanlardan, hakkında bilgi sahibi olması gereken yorumları davet edin. ortaya çıkarmasını sağlamaya yardımcı olur.
- İncelemenin ön koşulu olarak yazarın hangi yorumları ele alması gerektiğine karar verin. onaylayabilirsiniz.
- "LGTM" yaz (Bana İyi Görünür) ve teklifin mevcut durumundan memnundur.
Tüm tasarım inceleme istekleri için bu süreci izleyin. Tasarımları onaylama Yeşil Ofis’te değillerse Bazel’i tasarım endeksi.
Lider incelemecinin sorumlulukları
Uygulamayla ilgili karar vermekten siz sorumlusunuz olabilir. 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 inceleme uzmanlarının onayından sonra
- posta listesidir.
- 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 olmak; veya halkla ilişkiler kurun.
- 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).