ARCHITECTURE.md ekleyelim

 (matklad.github.io)
26 puan yazan xguru 2021-02-08 | 1 yorum | WhatsApp'ta paylaş

  • Açık kaynak katkısını kolaylaştırmak için, projenin mimarisini açıklayan bir dosyanın repoya eklenmesini öneren bir yazı

  • Projeye ara sıra katkı yapanlarla çekirdek geliştiriciler arasındaki en büyük fark, projenin mimarisine dair kavrayış düzeyi

  • Yapıya aşina değilseniz, bir patch yazmak 2 katından fazla zaman alır; ancak nerede değişiklik yapılacağını bulmak 10 katından fazla zaman alır

  • Yüksek seviyeli mimariyi açıklayan ARCHITECTURE.md gibi bir dosya yazın

→ Kısa yazın ki herkes okuyabilsin, yalnızca kolay kolay değişmeyen kısımları toparlayın

→ Kodla birebir senkron tutmaya çalışmayın, yılda yaklaşık iki kez yeniden gözden geçirin

İçerik yazma yöntemi

  • Çözülmeye çalışılan probleme kuşbakışı bir görünümle başlayın

  • Biraz daha ayrıntılı bir kod haritası: "X'i yapan şey nerede?"

  • Kabaca modülleri ve bunların ilişkilerini açıklayın: her modülün ne yaptığı başka belgelere bağlansın

  • Önemli dosya, modül ve tiplerin adlarını yazın

→ Okuyan kişinin ada göre arama yapabilmesini sağlayın; doğrudan link vermeyin (çünkü bağlantılar kırılabilir)

  • Katmanlar ile sistemler arasındaki sınırları açıkça belirtin
  • İyi örnekler

İlgili okumalar

1 yorum

 
xguru 2021-02-08

Ve mümkünse ana README.md içinde projenin her klasörüne dair açıklama eklenmesi yönündeki görüş de iyi görünüyor.

Örnek: https://github.com/diem/diem/…

Mümkünse her klasöre açıklama eklemek iyi olur; GitHub klasörde README varsa üst seviyede içeriğini gösterse güzel olurdu.

Bununla bağlantılı olarak Architecture Decision Records'a da göz atın.