Birleştirme kuyruğu: ajan dalları ana dalı bozmasın

Birleştirme kuyruğu, birden fazla yapay zekâ ajanıyla çalışırken ana dalı ayakta tutmanın en sağlam yoludur. Tek ajanla çalışırken sorun yoktur: ajan bir dalda çalışır, sen bakarsın, birleştirirsin. Ama aynı anda üç dört ajan kendi dalında iş bitirmeye başladığında tablo değişir. Her dal kendi başına testten geçer, sen hepsini sırayla birleştirirsin ve bir de bakarsın ki ana dal kırmızı.

Bu yazıda paralel ajan dallarının ana dalı neden bozduğunu, birleştirme kuyruğunun bu sorunu nasıl çözdüğünü ve AgentVera’daki birleştirme kuyruğunun adım adım nasıl çalıştığını anlatıyorum.

Ayrı ayrı yeşil, birlikte kırmızı

Bir örnekle başlayalım. Ana dalda formatPrice(amount) diye bir fonksiyon var. İki ajanı aynı anda çalıştırıyorsun:

• Ajan A, fonksiyona para birimi parametresi ekliyor: formatPrice(amount, currency). Bütün çağrıları da güncelliyor.
• Ajan B, yeni bir fatura ekranı yazıyor ve bu ekranda formatPrice(amount) çağırıyor.

İki dal da ana dalın aynı hâlinden çıktı. A’nın dalında testler geçiyor, çünkü A’nın gördüğü dünyada fatura ekranı yok. B’nin dalında da testler geçiyor, çünkü B’nin gördüğü dünyada fonksiyon hâlâ tek parametreli. Git açısından da çakışma yok: iki dal farklı dosyalara dokundu.

Önce A’yı, sonra B’yi birleştiriyorsun. Git hiçbir şey demiyor. Ama ana dalda artık tek parametreyle çağrılan iki parametreli bir fonksiyon var ve tip kontrolü kırılıyor.

Buna anlamsal çakışma denir. Metin olarak çakışma yoktur, ama değişiklikler birbirini bozar. Paralel ajanlarla bu durum sıklaşır, çünkü:

• Ajanlar birbirini görmez. Her biri kendi worktree’sinde çalışır ve diğerlerinin ne yaptığını bilmez.
• Dallar kısa sürede çoğalır. Bir öğleden sonra beş altı dal birleşmeyi bekleyebilir.
• Her dalın testi eski bir taban üzerinde koşmuştur. Dal ne kadar bekledikçe tabanı o kadar eskir.
• Elle sıralı birleştirme yorar. Her birleştirmeden sonra sıradaki dalı güncellemek, testi yeniden koşmak ve çakışmayı çözmek zaman ister. İnsan bunu atlamaya başlar.

Birleştirme kuyruğu nedir?

Birleştirme kuyruğu, ana dala girecek dalları sıraya koyan ve her birini ana dalın o anki ucu üzerinde birleştirip test eden bir düzendir. Fikir basit: bir dalı ana dala almadan önce, birleşmiş hâlini test et.

Sıradan bir akışla farkı şöyle:

GitHub’ın da depo düzeyinde bir merge queue özelliği var: pull request’leri kuyruğa alır ve hedef dalın son hâliyle birlikte test eder. AgentVera’nın kuyruğu aynı fikri masaüstünde, ajanların dalları için uygular ve birleştirme çakışmalarını ve kırılan kontrolleri bir ajana çözdürmeyi de işin içine katar.

AgentVera’da birleştirme kuyruğu nasıl çalışır?

Kuyruk, masaüstü uygulamasında Detaylar → Otomasyon → Birleştirme kuyruğu sekmesindedir. Her projenin bir kuyruğu vardır; birden fazla depolu projelerde her deponun kendi kuyruğu ve ayarları olur. Dallar ana dala tek tek girer.

1. Dal kuyruğa girer

Bir dalı kuyruğa üç yoldan alabilirsin:

• Elle: Kuyruk sekmesinde Dal alanına dal adını yazarsın, istersen bir Başlık verirsin ve Kuyruğa ekle dersin.
• Paralel ekipten: Paralel ekip işini bitirince Kuyruğa al düğmesiyle entegrasyon dalını kuyruğa gönderirsin.
• Otomasyondan: Bir otomasyon kuralında teslim şekli olarak Birleştirme kuyruğuna ekle seçersen, işi biten ajanın dalı doğrudan kuyruğa girer.

Bunlara ek olarak İnceleme kutusundaki kartlarda da Birleştirme kuyruğuna gönder kararı vardır. Kuyruktaki her iş, nereden geldiğini gösterir: elle, paralel ekip ya da otomasyon.

2. Ana dalın son hâli üzerinde birleştirilir

Sırası gelen dal, kuyruğun kendi ayrı worktree’sinde, hedef dalın o anki ucu üzerinde birleştirilir. Senin çalışma klasörüne ve ajanlarının klasörlerine dokunulmaz. Deponun bir uzak deposu varsa hedef dal önce çekilir ve birleştirme origin üzerindeki son hâlin üstünde yapılır.

Birleştirme şekli ayarlardan seçilir: Merge commit ya da Squash. Dal hedefte zaten varsa iş, ana dalda olarak işaretlenir.

3. Çakışma varsa bir ajan çözer

Birleştirmede çakışma çıkarsa kuyruk durmaz: bir çözücü ajan açılır ve iş “çakışma çözülüyor” durumuna geçer. Ajana iki tarafın amacını koruması, geride çakışma işareti bırakmaması ve sonucu commit etmesi söylenir.

Ajan işini bitirince AgentVera ona güvenmekle yetinmez, sonucu kendisi kontrol eder: birleşmemiş dosya kalmış mı, dosyalarda <<<<<<< ya da >>>>>>> işareti var mı, dal gerçekten birleşmiş mi. Bunlardan biri tutmazsa iş başarısız olur ve ana dala girmez.

Otomatik model seçimi açıksa çözücü ajanın modeli işin zorluğuna göre seçilir.

4. Kontrol birleşmiş sonuç üzerinde koşar

Birleşmiş sonuç hazır olunca kuyruk bir kontrol komutu çalıştırır. Kontrol alanını boş bırakırsan projenin test komutu kullanılır; istersen pnpm typecheck && pnpm test gibi kendi komutunu yazabilirsin.

Kontrol kırılırsa çözücü ajan çıktının son kısmıyla birlikte devreye girer ve hatayı düzeltmeye çalışır. En fazla iki düzeltme turu yapılır. Kontrol yine kırmızıysa iş geri atıldı durumuna geçer ve kuyruk sıradaki işe geçer. Kırık dal ana dala hiç girmez.

Yukarıdaki formatPrice örneğinde olacak olan tam olarak budur: B’nin dalı, A’nın girmiş olduğu ana dal üzerinde birleştirilir, tip kontrolü kırılır, çözücü ajan fatura ekranındaki çağrıyı yeni imzaya uydurur, kontrol yeşile döner.

5. Onay ve ana dala alma

Kontrolü geçen dal hazırdır. Varsayılan ayarda Geçenleri kendiliğinden ana dala al kapalıdır; iş “hazır, onay bekliyor” durumunda bekler ve sana bildirim gelir. Bakarsın, uygun görürsen Ana dala al dersin.

Ana dala alma şöyle olur:

• Uzak depo varsa birleşmiş sonuç hedef dala push edilir. GitHub depolarında bilgisayardaki GitHub girişin kullanılır.
• Uzak depo yoksa yerel hedef dal ileri sarılır. Commit edilmemiş işin varsa dal onun altından kaydırılmaz.
• Hedef dal arada ilerlediyse iş yeni uç üzerinde yeniden kurulur ve kontrol tekrar koşar. Bu en fazla üç kez denenir; hedef durmadan ilerliyorsa iş başarısız olur.

Uygulamayı kapatıp açtığında yarıda kalan iş kaybolmaz, yeniden sıraya girer.

Ayarlar

Kuyruğun ayarları azdır ve hepsi aynı sekmededir:

Kuyruktaki işler için Yukarı ve Aşağı ile sırayı değiştirebilir, İptal ile bir işi durdurabilir, başarısız ya da iptal edilmiş bir işi Yeniden dene ile tekrar başlatabilirsin. Her işin akışı ve geçmişi ayrı ayrı görünür; PR’ı olan işlerde PR’ı aç ile GitHub’a geçebilirsin.

Kuyruk arka planda çalışan diğer işlerle aynı kaynakları paylaşır ve öncelik sırasında ilk sıradadır: birleştirme, otomasyondan ve paralel ekipten önce gelir. Senin elle başlattığın ajanlar hiç sıraya sokulmaz.

Paralel ekip ve kuyruk birlikte

Birleştirme kuyruğu en çok paralel ekiple birlikte işe yarar. Paralel ekip büyük bir işi en fazla sekiz parçaya böler; varsayılan olarak aynı anda üç ajan, her biri kendi worktree’sinde çalışır. Parçalar bir entegrasyon dalında birleştirilir, çakışmaları ve kontrolü bir entegrasyon ajanı halleder.

Ekip bitince elinde tek bir entegrasyon dalı olur. Bu dalı Kuyruğa al ile kuyruğa gönderirsin. O sırada başka bir ekip ya da bir otomasyon da ana dala bir şey göndermiş olabilir; kuyruk hepsini sırayla ve her seferinde ana dalın son hâli üzerinde test ederek alır.

Paralel ajanlarla çalışma düzenini ayrıntılı görmek istersen paralel kodlama ajanları yazısına bakabilirsin.

Sık yapılan hatalar

• Kontrolü boş ve test komutu olmayan bir proje. Kuyruk birleştirir ama doğrulayacak bir şey yoksa anlamsal çakışmayı yakalayamaz. Projenin test komutunu tanımla ya da Kontrol alanına bir komut yaz.
• Kontrol olarak yalnızca birim testleri. Yukarıdaki örnekteki gibi hataların çoğu tip kontrolünde ya da derlemede çıkar. Kontrol komutuna tip kontrolünü de ekle.
• Otomatik almayı ilk gün açmak. Kuyruğun ne kadar güvenilir çalıştığını görmeden Geçenleri kendiliğinden ana dala al ayarını açma. Önce birkaç hafta onayla ilerle.
• Dev dallar. Kuyruk büyük dalları da alır, ama çakışma ve kırılma olasılığı dalın büyüklüğüyle artar. Ajanlara küçük ve odaklı işler ver.
• Geri atılan işi görmezden gelmek. Geri atılan bir iş genelde gerçek bir tasarım çatışmasına işaret eder. Akışına bak, gerekirse işi ajana notla geri gönder.

Örnek bir gün

Sabah

Üç iş için üç ajan başlatıyorsun: biri ödeme sayfasında, biri raporlama API’sinde, biri bağımlılık güncellemesinde. Her biri kendi worktree’sinde çalışıyor. Bir de geceden kalan bir CI kırığı var; onu bir otomasyon kuralı zaten yakalamış ve düzeltmeyi kuyruğa göndermiş.

Öğleden önce

Ajanlar işlerini bitirdikçe İnceleme kutusunda kartları açıp bakıyorsun. Ödeme sayfası ve raporlama API’si iyi görünüyor; ikisini de Birleştirme kuyruğuna gönder ile kuyruğa alıyorsun. Kuyrukta artık üç iş var: CI düzeltmesi, ödeme sayfası ve raporlama API’si.

Öğle

CI düzeltmesi kontrolü geçiyor, onay bekliyor. Ana dala al diyorsun. Ödeme sayfası, yeni ana dal üzerinde birleşiyor ve geçiyor. Raporlama API’si ise ödeme sayfasının değiştirdiği bir tiple çakışıyor; çözücü ajan devreye giriyor, çağrıları güncelliyor, kontrol yeşile dönüyor. Sen yalnızca iki onay veriyorsun.

Öğleden sonra

Bağımlılık güncellemesi kontrolde iki düzeltme turundan sonra hâlâ kırmızı, iş geri atılıyor. Ana dal temiz. Akışa bakıp sorunun bir kütüphanenin büyük sürüm değişikliği olduğunu görüyorsun ve işi daha dar bir talimatla ajana geri veriyorsun.

Kontrol listesi

• Projenin test komutu tanımlı mı, ya da Kontrol alanında bir komut var mı?
• Kontrol tip kontrolünü ve derlemeyi de kapsıyor mu?
• Hedef dal doğru mu? Boşsa varsayılan dal kullanılır.
• Birleştirme şekli ekibinin alışkanlığına uyuyor mu: Merge commit mi, Squash mı?
• Geçenleri kendiliğinden ana dala al bilinçli olarak mı açık ya da kapalı?
• GitHub depolarında bilgisayarda GitHub girişi yapılmış mı?
• Ajanlara verilen işler küçük ve odaklı mı?

Sonuç

Paralel ajanlar hızlıdır, ama hız ana dalı kırarak gelirse kazanç kısa sürer. Birleştirme kuyruğu her dalı ana dalın son hâli üzerinde birleştirip test ederek, ayrı ayrı yeşil olan dalların birlikte ana dalı kırmasını önler. AgentVera’da kuyruk çakışmaları ve kırılan kontrolleri bir ajana çözdürür, sonucu kendisi doğrular ve son sözü varsayılan olarak sana bırakır.

Daha fazlası için:

• Birleştirme kuyruğu
• Paralel ekip
• Git ve GitHub
• Git worktree ile paralel geliştirme
• Yapay zekâ ile kod incelemesi

AgentVera’yı denemek için ana sayfaya göz at.