Monorepo vs Polyrepo: Doğru Proje Yapısı

Monorepo polyrepo tartışması, bir projeyi büyütmeye başladığın anda kaçınılmaz olarak karşına çıkar. Tüm kodu tek bir Git deposunda mı tutacaksın, yoksa her servisi, paketi ya da uygulamayı ayrı depolara mı böleceksin? Doğru cevap "her zaman şu" değildir; ekibinin büyüklüğüne, dağıtım modeline ve araç zincirine bağlıdır. Bu yazıda iki yaklaşımı somut örneklerle karşılaştırıp, kendi projende hangisinin daha az acı vereceğine nasıl karar vereceğini anlatıyorum.

Temel kavramlar: monorepo ve polyrepo nedir?

Bir monorepo, birden fazla proje, paket veya servisin tek bir versiyon kontrol deposu altında yaşadığı yapıdır. Frontend, backend, paylaşılan kütüphaneler ve altyapı betikleri aynı git clone ile gelir. Klasik bir düzen şöyle görünür:

my-company/
├── apps/
│   ├── web/
│   └── admin/
├── packages/
│   ├── ui/
│   └── config/
└── services/
    └── api/

Bir polyrepo (çoklu repo) ise her bağımsız birim için ayrı bir Git deposu tutar: company-web, company-api, company-ui-kit gibi. Her depo kendi sürümünü, kendi CI hattını ve kendi erişim iznini taşır. İki yaklaşım da yıllardır üretimde kullanılır; mesele hangisinin senin kısıtlarına oturduğudur.

Monorepo'nun güçlü yanları

Monorepo'nun en büyük cazibesi tek bir doğruluk kaynağı sunmasıdır. Paylaşılan bir bileşeni değiştirdiğinde, onu kullanan tüm uygulamaları aynı commit içinde güncelleyebilirsin. Bu da "atomik değişiklik" demektir:

• Tutarlı bağımlılıklar: Tüm projeler aynı kütüphane sürümünü kullanır; "bende çalışıyordu" sorunları azalır.
• Kolay kod paylaşımı: Ortak bir ui paketini yeni bir depo yayınlamadan doğrudan içe aktarırsın.
• Çapraz kesen refactor: Bir API alanını yeniden adlandırırken hem sunucuyu hem tüm istemcileri tek pull request içinde düzeltebilirsin.
• Görünürlük: Tüm kod tek yerde olduğu için arama, gezinme ve standart belirleme kolaylaşır.

Bu nedenle birbirine sıkı bağlı, sık birlikte değişen kod tabanlarında monorepo genellikle daha az sürtünme yaratır.

Polyrepo'nun güçlü yanları

Polyrepo, net sınırlar ve bağımsızlık ister. Her takım kendi deposunu, kendi sürüm ritmini ve kendi dağıtım takvimini yönetir. Avantajları şunlardır:

• Daha küçük yüzey alanı: Bir geliştirici yalnızca ilgilendiği depoyu klonlar; checkout ve indeksleme hızlıdır.
• Bağımsız sürümleme: Her servis kendi semantik sürümünü etiketler; bir ekibin yayını diğerini beklemez.
• İnce taneli erişim: Hassas bir servisin deposuna yalnızca yetkili kişiler erişir.
• Basit CI: Her deponun CI hattı yalnızca o depoyu derler; "neyin değiştiğini" bulmak için ekstra zekaya ihtiyaç duymazsın.

Birbirinden gerçekten bağımsız, farklı dillerde yazılmış ya da farklı yaşam döngülerine sahip servislerde polyrepo doğal akar.

Ölçeklenme ve araç zinciri etkisi

Karar verirken asıl belirleyici çoğu zaman araçlardır. Monorepo büyüdükçe naif kurulumlar yavaşlar: her commit'te her şeyi yeniden derlemek istemezsin. Bu yüzden monorepo'lar genellikle bir görev çalıştırıcıya yaslanır. JavaScript/TypeScript ekosisteminde turborepo, nx veya pnpm workspaces yaygındır; bunlar yalnızca etkilenen paketleri derler ve sonuçları önbelleğe alır.

# pnpm workspace tanımı
# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

Polyrepo'da ise bu sorun yer değiştirir: derleme basit kalır ama bağımlılık yönetimi zorlaşır. Paylaşılan kütüphaneyi bir paket kayıt defterine (örneğin özel npm registry ya da Composer için Packagist alternatifi) yayınlaman, sonra her tüketici deponun sürümü güncellemesi gerekir. Bu, sürüm dağılımı (version skew) riskini artırır: depo A kütüphanenin 2.1 sürümünü, depo B ise hâlâ 1.8 sürümünü kullanıyor olabilir.

Hangisini seçmelisin?

Pratik bir karar çerçevesi şöyle:

• Monorepo'yu tercih et: Küçük-orta bir ekipsen, kod tabanları birbirine sıkı bağlıysa, sık çapraz değişiklik yapıyorsan ve nx/turborepo gibi bir araca yatırım yapmaya hazırsan.
• Polyrepo'yu tercih et: Bağımsız çalışan birden çok ekibin varsa, servisler farklı dillerde ve yaşam döngülerindeyse, sıkı erişim ayrımı gerekiyorsa ve net API sözleşmeleriyle gevşek bağlılık istiyorsan.

Üçüncü bir yol da var: kademeli geçiş. Birçok ekip ilgili birkaç servisi tek monorepo'da toplar ama tamamen ayrık ürünleri ayrı tutar. "Saf" olmak zorunda değilsin; sınırı, kodun birlikte değişme sıklığına göre çiz.

Sık Sorulan Sorular

Monorepo Git'i yavaşlatır mı?

Çok büyük geçmişlerde olabilir, ama çoğu proje için sorun değildir. Depo gerçekten devasa hâle gelirse git clone --filter=blob:none ile partial clone ya da sparse-checkout kullanarak yalnızca ihtiyacın olan klasörleri indirebilirsin.

Mikroservis kullanıyorsam polyrepo şart mı?

Hayır. Mimari (mikroservis) ile depo yapısı (monorepo/polyrepo) birbirinden bağımsız kararlardır. Onlarca mikroservisi tek monorepo'da tutan büyük ekipler vardır; bağımsız dağıtım yine de mümkündür.

Sonradan birinden diğerine geçebilir miyim?

Evet. git subtree veya git filter-repo ile depoları geçmişiyle birlikte birleştirip bölebilirsin. Geçiş ucuz değildir ama mümkündür; bu yüzden başlangıç kararına aşırı yüklenme.

Projen için doğru yapıyı birlikte netleştirelim. Mevcut depolarını, CI hattını ve ekip akışını gözden geçirip sana uygun monorepo veya polyrepo kurulumunu kuralım. Benimle iletişime geç ve ihtiyacını konuşalım.