Laravel Maestro Başlangıç Kitlerine Katkıda Bulunma Sürecinde Değişikliklerinizi Kaybetmeme Yöntemleri

Maestro Nedir?

Maestro, Laravel başlangıç kitlerini oluşturmak ve yönetmek için kullanılan bir üst düzey jeneratör deposudur.

Aşağıdaki başlangıç kiti depoları, Maestro’dan türetilmiş alt düzey depolar olup, başlangıç kiti tarafında doğrudan yapılan değişiklikler yukarıya yansıtılmaz.

• laravel/react-starter-kit
• laravel/vue-starter-kit
• laravel/svelte-starter-kit

Bu nedenle, aşağıdaki gibi değişiklikler yaparken maestro tarafında değişiklik yapmanız gerekir.

• Paylaşılan başlangıç kiti hata düzeltmeleri
• Çapraz çeşit düzeltmeleri
• Jeneratör düzeyinde spesifikasyon değişiklikleri
• Staklar arasında UI tutarlılığı ayarlamaları

Maestro Yapısı

Normal bir Laravel uygulamasından farklı olarak, Maestro aşağıdaki yapıya sahiptir.

• kits/ — kaynak şablon
• build/ — üretilmiş uygulama (üretim zamanı)
• watcher — build/ → kits/ arasında senkronizasyon katmanı

Inertia Çeşit Matriksi

Bu durum Vue / Svelte için de geçerlidir.

Eğer “gerçeklerin kaynağı” anlamını yanlış anlaşırsanız, istenmeyen geri alma işlemleri ve gereksiz farklar meydana gelmesi olasılığı yüksektir.

Temel İlkeler

kits/ Gerçeklerin Kaynağıdır

Kaydedilmesi gereken her fark kits/ içinde olmalıdır. build/ üretilmiş bir çıktıdır ve doğrulama, geçici düzenlemeler ve çalışma zamanı testleri için bir çalışma dizini olarak değerlendirilmelidir.

build/ tarafından farklar kaydedilmemelidir.

build/ Atılabilirdir

build/‘i her zaman yeniden oluşturulabilir bir şey olarak düşünün. İçeriği çeşitler değiştiğinde önemli ölçüde değiştiği için, kalıcı değişiklikler, kaynak yamanları veya sürekli düzeltmeler doğrudan build/‘de yer almamalıdır. Kalıcı değişiklikler kits/‘de olmalıdır.

composer kit:run Kolaydır Ama Tehlikelidir

composer kit:run, ayarları, Laravel geliştirme sunucusunu, Vite geliştirme sunucusunu ve izleyiciyi bir arada çalıştıran bir kolaylık komutudur.

Ancak izleyici, build/‘i yetkili olarak değerlendirir ve değişiklikleri kits/‘ye geri yazar. Sonuç olarak, eski bir build/ kullanarak kit:run başlatırsanız, kits/‘deki değişiklikler geri alınabilir.

kits/ içinde doğrudan düzenleme yaptıktan sonra, eski bir build/ ile asla composer kit:run çalıştırmayın. Öncelikle her zaman yeniden oluşturun.

İlk Kurulum

git clone https://github.com/laravel/maestro.git
cd maestro/orchestrator

composer install
npm install

Bir Başlangıç Kitini Oluşturma

Çalışmaya başlangıçta, hedef çeşidi build/ dizinine genişletin.

cd orchestrator

php artisan build --kit=react
php artisan build --kit=vue
php artisan build --kit=svelte

php artisan build --kit=react --workos
php artisan build --kit=react --teams

Mevcut oluşturma hedefi şu konumda saklanır:

orchestrator/storage/app/private/starter_kit

Geliştirme Sunucusunu Başlatma

Doğrudan build/ dizininde başlamayın. Bunun yerine, orchestrator/ dizininden şu komutu çalıştırın.

composer kit:run

Bu komut birlikte aşağıdakileri gerçekleştirir:

• build/ dizininde composer setup çalıştırır
• Laravel geliştirme sunucusunu başlatır
• Vite geliştirme sunucusunu başlatır
• İzleyiciyi başlatır

Tipik uç noktalar:

• Laravel: http://localhost:8000
• Vite: http://localhost:5173

Güvenli İş Akışı

Şablon 1: build Tarafında Düzenleme (geçici doğrulama için)

build → kit:run → edit build → verify behavior

Keşifsel UI ayarlamaları için uygundur. Ancak build/‘in atılabilir olması nedeniyle, son kaynak yamaları kits/‘ye yeniden düzenlemek daha güvenli olacaktır.

Şablon 2: kits Tarafında Düzenleme (PR’lar için önerilen yol)

edit kits → php artisan build ... → composer kit:run → verify

Bu, PR yamaları hazırlarken önerilen yaklaşımdır.

Çeşit Değiştirme

Mevcut bir build/‘i kısmen güncellemeyin. Her seferinde yeniden oluşturun.

php artisan build --kit=react
php artisan build --kit=vue
php artisan build --kit=svelte

Değiştikten sonra her seferinde doğrulama için composer kit:run‘yi yeniden çalıştırın.

Doğrulama Notları

Veritabanı Başlatma

composer setup sadece php artisan migrate --force kadar çalışır. Eğer veri eklenmesi gerekiyorsa, build/ içinde şu komutu çalıştırın.

php artisan migrate:fresh --seed

İzleyiciden Eski Dosyaları Kaldırma

Çeşit değiştirirken, izleyici bazı kaynak varlıkların eski olduğunu belirleyebilir ve bunları silebilir.

Örnekler:

• kits/Inertia/Fortify/React/chisel-paths.php
• kits/Inertia/Fortify/Vue/chisel-paths.php
• kits/Inertia/Fortify/Svelte/chisel-paths.php

Bunları ana değişiklik setinden ayrı olarak ele alın.

UI Kopya Değişikliklerini Doğrulamak için Örnek Yollar

Fortify çeşidinde UI metin değişiklikleri için, genellikle ana akışları doğrulamak için aşağıdaki yollar yeterlidir.

• /login
• /user/confirm-password
• /verify-email
• /settings/security
• /settings/appearance
• /settings/profile

WorkOS’in daha yüksek bir doğrulama maliyeti olduğundan, küçük değişiklikler için Fortify çeşitlerini önceliklendirmek kabul edilebilir.

Sahneleme Hakkında Düşünme

PR’nin ana amacı bir UI metin değişikliği ise, yalnızca metinle ilgili farklılıkları sahneleyin.

Aşağıdakilerin genellikle ayrı tutulması gerekir:

• chisel-paths.php izleyici tarafından silinmiş
• Geçici düzeltmeler build/‘de
• Tarayıcı testleri için doğrulamalar
• İlgisiz çalışma zamanı hata düzeltmeleri

# Tüm dosyaları eklemek yerine, hedef dosyaları açıkça ekleyin
git add kits/path/to/changed-file.blade.php

PR Öncesi Kontrol Listesi

• [ ] build/‘den herhangi bir sahnelemeden fark var mı?
• [ ] İzleyiciden çıkarılan eski dosyalar karışmış mı?
• [ ] Gereksiz çapraz çeşitleme farkları var mı?
• [ ] Geçici tarayıcı test değişiklikleri hala mevcut mı?
• [ ] git diff --cached kontrol edildi mi?
• [ ] Gerçeklerin kaynağı doğru bir şekilde kits/ tarafında mı?

Özet

Maestro’yu normal bir Laravel uygulaması gibi yönetirseniz, fark geri almaklar ve gereksiz gönderimler tetiklemek oldukça kolaylaşır. PR’leri güvenli bir şekilde oluşturmak için aşağıdaki sıralamayı koruyun.

Güvenli PR Akışı

1. Değişiklikleri kits/ içinde uygulayın
2. php artisan build ... ile yeniden oluşturun
3. composer kit:run ile doğrulayın
4. Yalnızca amaçlanan farklılıkları sahneleyin
5. İzleyici/tarayıcı test yan etkilerini ayırın