Meet Maestro: Come Gestiamo 21 Varianti dei Laravel Starter Kit | Laravel - Il stack pulito per Artisans e agenti

Mantenere gli starter kit è divertente quando stai costruendo nuove cose. Diventa molto meno divertente quando devi trasportare la stessa modifica attraverso più framework, flussi di autenticazione e combinazioni di funzionalità ripetutamente.

Questa era la situazione in cui ci imbattevamo continuamente con i Laravel Starter Kit. Una modifica arrivava in Laravel, oppure miglioravamo una variante dello starter kit, e poi iniziava il vero lavoro: capire come trasferire quella stessa modifica al resto della matrice senza perdere nulla o introdurre incongruenze.

Uno script interno aiutava con la sincronizzazione upstream da Laravel, ma anche solo riuscire a incorporare le modifiche era solo metà della battaglia. Propagarle in modo pulito attraverso tutte le varianti era ancora troppo manuale.

È qui che entra in gioco Maestro, un orchestratore per i Laravel Starter Kit. Invece di aggiornare ripetutamente a mano molti repository degli starter kit, Maestro ci permette di definire un sistema che li costruisce in modo coerente. Aggiorna una volta i livelli sorgente corretti, e lo strumento si occupa del resto.

In questo articolo, mostro il problema che ha portato a Maestro, come i contributori possono usarlo per lavorare sugli starter kit, e alcune delle idee tecniche al suo interno che trovo particolarmente interessanti.

Il Vero Problema della Manutenzione degli Starter Kit

La parte difficile degli starter kit non è costruire la prima versione. La parte difficile è farli evolvere una volta che hai una matrice crescente di framework, approcci di autenticazione e combinazioni di funzionalità da tenere sincronizzati.

Una volta che hai più framework e più varianti di autenticazione, ogni miglioramento inizia a diramarsi:

1. Questa modifica appartiene a tutti i kit o solo a uno stack?
2. È condivisa tra Fortify e WorkOS?
3. Colpisce anche le varianti con Teams?
4. È diversa per React, Vue e Svelte?
5. Se la modifica riguarda l'interfaccia utente, la denominazione delle pagine o la struttura dei componenti è diversa per ogni framework?

Ora immagina di fare tutto questo su 8 repository e 21 varianti.

Questa configurazione crea alcuni problemi molto reali:

• Le modifiche diventano ripetitive.
• Mantenere le varianti sincronizzate diventa più difficile nel tempo.
• I contributori hanno bisogno di troppa conoscenza specifica del repository.
• Le regressioni si insinuano perché un repository viene aggiornato e un altro no.
• I refactoring diventano costosi perché la stessa idea deve essere ripetuta molte volte.

Questo è il tipo di problema che prosciuga lentamente i manutentori. Niente è singolarmente impossibile, ma tutto diventa più pesante di quanto dovrebbe essere.

Quindi, invece di chiedere ai contributori di pensare prima in termini di repository, Maestro cambia il flusso di lavoro e chiede loro di pensare in termini di livelli dello starter kit e varianti costruite.

Cosa è Realmente Maestro

A livello generale, Maestro è un orchestratore per i Laravel Starter Kit.

Lavori in un unico repository, costruisci la variante esatta dello starter kit che desideri, apporti le tue modifiche lì e lasci che Maestro sincronizzi quelle modifiche nei livelli sorgente corretti. Dopo che la PR è stata unita, Maestro può automaticamente inviare le modifiche ai repository degli starter kit interessati.

Questo è un cambiamento molto importante. Invece di mantenere manualmente ogni repository finale, i repository finali diventano output di un sistema. La fonte di verità vive in un unico posto.

E questo conta molto quando la stessa funzionalità può esistere in più varianti con solo piccole differenze.

Diagramma affiancato che confronta la manutenzione manuale degli starter kit con il flusso di lavoro semplificato di Maestro.

Come I Contributori Possono Lavorare Sugli Starter Kit Usando Maestro

Dal punto di vista del contributore, il flusso di lavoro è sorprendentemente semplice.

Prima, dalla directory orchestrator, costruisci la variante dello starter kit su cui vuoi lavorare:

Se sai già la variante esatta che vuoi, puoi costruirla direttamente:

Questo crea una directory build con la versione eseguibile di quello starter kit.

Poi avvii il kit localmente, sempre dalla directory orchestrator:

È qui che il flusso di lavoro diventa davvero piacevole. Non modifichi direttamente la struttura sorgente a strati profondi. Lavori sul kit costruito all'interno di build, che sembra di lavorare su una normale applicazione Laravel. Nel frattempo, un watcher tiene traccia delle tue modifiche e le copia nei posti giusti sotto kits/.

Questo rende il contributo molto più accessibile perché puoi concentrarti sulla funzionalità o sul bug fix, non sul ricordare l'intero modello di stratificazione interna prima di scrivere una singola riga di codice.

Quando vuoi validare le tue modifiche su più varianti, Maestro ti fornisce anche comandi dedicati per questo:

E se vuoi restringere l'esecuzione a una matrice più piccola, puoi farlo anche tu:

Questo è un grande miglioramento della qualità della vita per i contributori. Riduce il sovraccarico cognitivo pur dando ai manutentori la fiducia che una modifica si comporti correttamente attraverso la matrice.

Come Maestro Costruisce le Varianti

Una delle idee più interessanti in Maestro è che gli starter kit sono modellati come un insieme di livelli componibili.

Ad esempio, una variante non è memorizzata come un unico enorme codebase indipendente. Invece, è assemblata da pezzi condivisi e pezzi specifici del framework.

Il processo di build per un kit Inertia segue una composizione a livelli come questa:

Per Livewire, la stratificazione è diversa, ma l'idea è la stessa: partire da fondamenta condivise, poi aggiungere il comportamento del framework, poi aggiungere il comportamento specifico dell'autenticazione e infine aggiungere funzionalità più specifiche come Teams o Components.

Questo dà a Maestro alcuni vantaggi importanti:

• I file condivisi vivono solo una volta.
• Le override specifiche del framework rimangono isolate.
• Il processo di build può produrre un kit completo eseguibile da un albero sorgente a strati.
• I contributori non devono duplicare manualmente le modifiche su ogni variante finale.

Se guardi l'implementazione del comando build, è esattamente quello che fa. Copia i livelli base in build, poi applica i livelli corretti specifici dello stack e della variante sopra.

Questo significa che lo starter kit finale costruito non è magico, ma una composizione deterministica di livelli.

E onestamente, questo è il modello giusto per questo tipo di problema di manutenzione.

Diagramma dell'architettura a livelli che mostra come i livelli condivisi, specifici del framework, specifici dell'autenticazione e specifici dei team si combinano in uno starter kit costruito.

La Parte Intelligente: Sincronizzare le Modifiche al Livello Giusto

Costruire varianti è già utile, ma la parte davvero intelligente di Maestro è la direzione inversa.

I contributori sono tenuti a fare modifiche in build, non direttamente nella struttura kits/ a strati. Quindi il sistema deve rispondere a una domanda più difficile:

Quando un file cambia nel kit costruito, dove dovrebbe andare quella modifica nei livelli sorgente?

È qui che la logica del watcher diventa interessante.

Maestro mantiene un manifest con l'ordine dei livelli per ogni variante del kit. Quando un file cambia, controlla il set di livelli attivo per quella variante e sceglie la cartella con priorità più alta che possiede già quel file. Se il file non esiste ancora, cade nel livello più specifico.

In pratica, ciò significa che una modifica non viene copiata ciecamente in una cartella condivisa solo perché esiste. La sincronizzazione preferisce il punto di proprietà valido più specifico, che è esattamente ciò che vuoi se stai cercando di evitare perdite accidentali tra varianti.

La logica è concettualmente molto vicina a questa:

Questa piccola idea ha un grande peso. Significa che Maestro non solo genera starter kit, ma preserva anche l'architettura dell'albero sorgente a strati mentre modifichi un build eseguibile.

I contributori modificano lo starter kit costruito, mentre Maestro decide dove quelle modifiche appartengono nell'albero sorgente a strati.

Il Ripristino dei Placeholder è un Altro Grande Dettaglio

C'è un altro dettaglio tecnico che mi piace particolarmente in Maestro.

Per gli starter kit Inertia, alcuni nomi di pagina specifici del framework differiscono tra React, Vue e Svelte. Ad esempio, una pagina può chiamarsi dashboard in React ma Dashboard in Svelte e Vue. Durante il passo di build, Maestro sostituisce i placeholder con i valori corretti specifici del framework.

Sembra semplice, ma quando si sincronizzano le modifiche da build, il watcher deve evitare di hardcodare quei nomi di framework nei file sorgente condivisi.

Quindi il watcher ripristina i placeholder prima di scrivere i file in kits/.

Questo significa che i livelli sorgente possono mantenere valori placeholder riutilizzabili come {{dashboard}}, mentre l'app costruita ottiene comunque i nomi di pagina concreti richiesti dal framework scelto.

Questo è uno di quei dettagli che ti dice che lo strumento è stato progettato per la manutenibilità, non solo per la generazione di output.

È anche un forte esempio di qualcosa che apprezzo sempre negli strumenti: proteggi la fonte di verità dalle trasformazioni specifiche della convenienza.

Dare una Struttura alla Complessità

Ciò che mi piace di più di Maestro è che non cerca di nascondere la complessità fingendo che la matrice non esista. La matrice è reale. Le varianti sono reali. Le differenze tra framework sono reali.

Quello che fa Maestro è dare a questa complessità una struttura.

Invece di spargere il peso della manutenzione su molti repository, centralizza la logica. Invece di chiedere ai contributori di memorizzare come tutte le varianti si relazionano tra loro, fornisce loro un ambiente eseguibile e un meccanismo di sincronizzazione. Invece di trattare ogni repository di starter kit come un prodotto completamente isolato, li tratta come output di un sistema a strati.

Questo è un modello di manutenzione molto più sano.

E per i contributori open source, crea un'esperienza molto migliore:

• Scegli la variante che vuoi migliorare.
• Costruiscila.
• Esegui.
• Fai la modifica in un'applicazione reale.
• Lascia che Maestro sincronizzi i livelli sorgente.
• Valida la matrice con i comandi forniti.
• Apri la PR.

Questo flusso è pratico, insegnabile e scalabile.

Pull Request che Mostrano Perché Maestro Funziona

Il modo migliore per capire Maestro è guardare i tipi di pull request che abilita.

Alcune modifiche devono raggiungere quasi l'intera matrice. Altre dovrebbero rimanere limitate a un framework o a una variante di funzionalità. Maestro rende entrambi i tipi di modifiche molto più facili da gestire.

Ecco alcuni buoni esempi reali.

Modifiche che Colpiscono Quasi Tutti i Kit

#51 - Update Vite ecosystem to v8 across all starter kits

Questo è un ottimo esempio di modifica di manutenzione ampia. La PR aggiorna l'ecosistema Vite in tutti gli starter kit, inclusi aggiustamenti specifici del framework come l'aggiornamento del plugin Vite Svelte e una decisione di compatibilità specifica per React sulla versione del plugin Vite.

Questo tipo di modifica è esattamente dove uno strumento come Maestro brilla. Invece di coordinare aggiornamenti di dipendenze simili su molti repository manualmente, l'aggiornamento può essere fatto nel sorgente a strati e propagato coerentemente dove necessario.

#35 - Add password visibility toggle to all starter kits

Questa è un miglioramento rivolta al prodotto che tocca molta matrice. Aggiunge la stessa funzionalità di usabilità nei kit Inertia e nei kit Livewire, ma l'implementazione è comunque consapevole dello stack: Inertia ottiene componenti PasswordInput dedicati per ogni framework, mentre Livewire usa il supporto viewable di Flux.

Questo è un esempio molto realistico di come Maestro aiuta a mantenere la coerenza senza forzare ogni stack alla stessa identica implementazione.

Modifiche che Colpiscono Varianti Specifiche

#63 - Add TeamPermission enum for type-safe permissions

Questa PR è un buon esempio di modifica con scope di funzionalità. Tocca solo il livello Teams, il che significa che l'aggiornamento è condiviso dagli starter kit che supportano i team, mentre le varianti blank e non-team rimangono intatte.

Questo è uno dei più grandi vantaggi del modello a livelli. Non devi ricordare manualmente ogni repository interessato. Modifichi il livello giusto una volta, e il set corretto di varianti riceve l'aggiornamento.

#27 - Update prettier config for Svelte and apply linter changes

Questa è chiaramente specifica per Svelte. Aggiorna le regole di formattazione Svelte e applica le modifiche di lint risultanti solo agli starter kit Svelte.

Senza orchestrazione, questo tipo di manutenzione specifica del framework può essere ancora fastidiosa perché devi tracciare tutti gli output dei kit basati su Svelte. Con Maestro, l'ambito è molto più chiaro perché la struttura sorgente modella già quella separazione.

#46 - Move React TooltipProvider to app root to match new shadcn preset contract

Questa PR è ancora più ristretta: colpisce solo gli starter kit React. La modifica è legata al comportamento UI specifico di React e alle aspettative del preset shadcn, quindi non dovrebbe propagarsi in Vue, Svelte o Livewire.

Maestro aiuta molto anche qui. Permette ai manutentori di fare fix altamente mirati a livello di framework mentre lavorano comunque all'interno di un unico sistema orchestrato, piuttosto che saltare tra repository.

Se guardi questi esempi insieme, puoi vedere il valore molto chiaramente:

• Le modifiche ampie possono essere applicate coerentemente quasi a tutta la matrice.
• Le modifiche specifiche della variante possono rimanere isolate ai livelli esatti a cui appartengono.
• Contributori e manutentori possono ragionare sull'ambito molto più facilmente.

Prova i Laravel Starter Kit

Quando un progetto cresce da pochi starter kit a 21 varianti distribuite su 8 repository, la manutenzione smette di essere solo codice e diventa design di sistema.

Maestro trasforma un problema di manutenzione frammentato in un flusso di lavoro orchestrato. Dà ai contributori un modo migliore per lavorare sugli starter kit. E usa internals molto riflessivi, come build a livelli, sincronizzazione basata su priorità e ripristino dei placeholder, per mantenere pulita la fonte di verità mentre rende semplici i contributi quotidiani.

Se vuoi costruire con Laravel, i Laravel Starter Kit sono il modo più veloce e facile per iniziare a costruire la tua app. Se li hai provati e vuoi contribuire, vai al repository GitHub di Maestro. Apprezziamo tutti i tuoi contributi!

Potrei essere di parte, ma penso che questo sia un grande esempio di sforzo ingegneristico investito nel posto giusto. Non solo nelle funzionalità, ma nel processo che mantiene quelle funzionalità manutenibili nel tempo.