Conclusione principale: una pipeline CI verde dimostra che i controlli automatizzati sono stati superati; non significa che una pull request dell'App Store sia stata approvata. Se una proposta dell'app CasaOS/ZimaOS è rimasta aperta per mesi, smetti di ricontrollare gli stessi badge e determina quale livello è ancora in sospeso: validazione del repository, feedback dei revisori, requisiti di fusione o revisione del maintainer.
L'esempio concreto alla base di questa pagina era insolitamente ben preparato: l'app era stata migrata al formato v2, i controlli erano verdi, i tag Docker erano bloccati, i metadati erano completi e il contributore poneva una semplice domanda: «C'è qualcosa che blocca la fusione o qualche modifica necessaria da parte mia?»
Per prima cosa, verifica i controlli che contano davvero per l'attuale repository dell'App Store
L'attuale flusso di contributo all'App Store chiede ai contributori di creare un fork del repository, apportare e testare le modifiche, quindi aprire una pull request spiegando cosa è cambiato e come è stato verificato.
Per la validazione locale, il repository chiede specificamente ai contributori di eseguire:
./scripts/build_dist.shUn risultato corretto è più specifico di «il mio file Compose sembra a posto». La build dovrebbe completarsi senza errori, produrre dist/index.jsone generare l'app modificata in dist/apps/<app-id>/.
I controlli CI dell'App Store del repository eseguono la validazione di Compose e un controllo completo della build v2 sulle pull request. YAML non valido, metadati obbligatori dell'app mancanti, risorse referenziate mancanti o incompatibilità tra architetture possono causare il fallimento della build.
La CI verde è necessaria, ma non determina la fusione
Questo è il punto che molti contributori trascurano. Un controllo automatizzato completato con successo indica soltanto che il commit ha soddisfatto le condizioni verificate da quel controllo. I controlli dello stato di GitHub sono separati dalle decisioni di revisione e fusione.
Una pull request può rimanere aperta perché richiede:
- una revisione da parte di un maintainer o del responsabile del codice;
- le modifiche richieste da apportare;
- il branch da aggiornare;
- un conflitto di fusione da risolvere;
- decisioni di accettazione o di selezione specifiche del repository che la CI non può prendere.
I requisiti di unione di GitHub considerano le revisioni, le verifiche di stato e le regole del branch come condizioni di unione separate.
Usa la PR stessa per identificare il blocco
Prima di pubblicare un altro commento “ci sono aggiornamenti?”, controlla quattro sezioni:
- Verifiche: conferma che l’ultimo commit, non uno SHA precedente, abbia superato i workflow richiesti.
- Conversazione: cerca commenti dei manutentori o richieste di modifica ancora irrisolti.
- File modificati: verifica che la migrazione v2 non abbia lasciato metadati legacy nella posizione sbagliata.
- Riquadro di unione: GitHub normalmente indica se sono ancora necessarie una revisione, una verifica di stato, la risoluzione di conflitti o l’aggiornamento del branch.
Se la CI è verde e il riquadro di unione non mostra alcun blocco risolvibile dal contributore, il passaggio successivo probabilmente è la revisione umana, non un’altra modifica al codice.
Per le proposte v2, convalida il contratto sorgente, non solo il container Docker
Un container funzionante non è automaticamente una voce valida nell’App Store. L’attuale protocollo v2 prevede che la definizione dell’app sorgente contenga la configurazione runtime Docker Compose standard e un blocco di metadati x-casaos di primo livello. Lo schema dei metadati x-casaos definisce campi come id, main, index, port_map, icon, title, la categoria, l’architettura e i metadati della versione.
Quindi, quando una proposta afferma “CI superata”, il follow-up utile non è “SonarQube è passato?”, ma:
- L’app
./scripts/build_dist.shpassa sull’ultimo branch? - L’app genera l’output v2 previsto?
- Tutte le icone, le miniature e le schermate a cui si fa riferimento sono raggiungibili?
- L’architettura dichiarata corrisponde all’immagine?
- La versione e i metadati della release sono aggiornati?
- Tutti i commenti della revisione sono stati risolti?
Come chiedere un aggiornamento senza creare rumore
Se la proposta è rimasta inattiva a lungo, pubblica un solo aggiornamento di stato conciso invece di ripetere la presentazione originale completa. Un buon messaggio di follow-up è questo:
PR: #888
Ultimo commit: <SHA>
Build v2: superata con ./scripts/build_dist.sh
GitHub Actions: esito positivo sull'ultimo commit
Commenti di revisione aperti: nessuno
Ciò che mi serve: conferma dell'eventuale blocco ancora presente lato manutentoreIn questo modo il manutentore riceve subito una domanda a cui può rispondere.
Se la revisione dello store ufficiale è lenta, uno store di terze parti è un canale di distribuzione valido
L'ecosistema v2 non è limitato a un solo repository. ZimaOS documenta anche la configurazione di store di terze parti per repository compatibili. Se un'app necessita di una distribuzione tramite la community prima dell'integrazione ufficiale, pubblicarla tramite uno store di terze parti gestito può essere un'alternativa pratica mentre la PR originale rimane aperta.
Per gli utenti, anziché per i contributori, l'ZimaOS App Store spiega il modello delle app con un clic e il concetto di store di terze parti. La piattaforma per app ZimaOS offre una panoramica aggiornata dell'ecosistema. Se stai creando un host compatto per testare app basate intensivamente su Docker, ZimaBoard 2 è una piattaforma di test x86 pertinente, non un requisito per inviare un'app.
FAQ
Il superamento della CI significa che la mia app dovrebbe essere già stata integrata?
No. La CI dimostra solo ciò che convalidano i flussi di lavoro automatizzati. La revisione umana, le regole del repository, i commenti irrisolti, i conflitti e le decisioni dei manutentori sono aspetti separati.
Qual è il comando di convalida locale più utile per l'App Store attuale?
La guida al contributo del repository rimanda a ./scripts/build_dist.sh. Verifica che termini correttamente e produca i file v2 previsti.
Devo continuare a modificare il codice se tutti i controlli hanno esito positivo?
Non senza un motivo specifico. Prima esamina il riquadro di merge e i commenti di revisione. Se non ci sono blocchi risolvibili dal contributore, chiedi quale sia la decisione di revisione rimanente invece di apportare modifiche speculative.
Posso pubblicare l'app al di fuori dello store ufficiale?
Sì. La documentazione attuale della v2 supporta esplicitamente gli store ZimaOS compatibili di terze parti, quindi uno store esterno può essere un canale di distribuzione legittimo.
