Checklist di consegna del codice sorgente per clienti e agenzie

Cosa dovrebbe ottenere una consegna del codice sorgente

La consegna del codice sorgente è il momento in cui il progetto smette di essere “qualcosa che l'agenzia può gestire” e diventa “qualcosa che il cliente può possedere”. Senza una consegna chiara, i problemi comuni emergono in fretta: l'app si compila solo su un laptop, la produzione dipende da un segreto che nessuno trova, o un piccolo aggiornamento si trasforma in giorni di tentativi.

L'obiettivo di qualsiasi checklist di consegna del codice sorgente è semplice: dopo il trasferimento, il cliente deve essere in grado di costruire, eseguire e distribuire il prodotto senza aver bisogno che l'agenzia sia in standby. Questo non significa “mai più supporto”. Significa che le basi sono ripetibili e documentate, così la prossima persona può riprendere il lavoro con fiducia.

Cosa conta come deliverable deve essere esplicito. Come minimo, una consegna completa di solito include:

• Il repository completo (inclusi file di deployment e script di migrazione)
• Documentazione di setup che funziona su una macchina pulita
• Trasferimento degli accessi (account, permessi e dove risiede il sistema)
• Un runbook per attività di routine (deploy, rollback, backup, log)
• Un tag o snapshot finale “conosciuto-buono” che il cliente può citare

L'ambito conta tanto quanto il contenuto. Alcune consegne coprono solo un ambiente (per esempio, production). Altre includono dev, staging e production con impostazioni e processi separati. Se non si nomina quali ambienti sono inclusi, le persone assumono cose diverse, ed è lì che avvengono gli outage.

Un modo pratico per definire il successo è un test di verifica: una persona che non ha costruito l'app può esportare il codice (per esempio da una piattaforma come Koder.ai), seguire la documentazione, impostare le variabili d'ambiente, eseguire le migrazioni, compilare e distribuire nell'ambiente concordato.

Questa checklist si concentra sulla prontezza tecnica: variabili d'ambiente, rotazione dei segreti, migrazioni database, script di deployment e verifica delle build. Non copre termini legali, contratti, clausole di proprietà intellettuale o controversie di pagamento. Anche quelli sono importanti, ma appartengono a un accordo separato.

Prima di esportare: concorda proprietà e tempistiche

Una consegna pulita inizia prima di qualsiasi esportazione. Se concordate chi possiede cosa e quando, eviterete sorprese dell'ultimo minuto come deployment interrotti, hosting non pagato o accessi mancanti.

Fissa la data di consegna e una finestra di freeze breve

Scegliete una data di consegna e definite una finestra di freeze (spesso 24-72 ore) in cui vanno fatte solo correzioni urgenti. Questo mantiene il codice esportato e il sistema in esecuzione sincronizzati. Se serve un hotfix durante il freeze, annota esattamente cosa è cambiato e assicurati che sia incluso nell'export finale.

Chiarisci la proprietà di account e fatturazione

Decidete chi possiederà DNS, cloud hosting e eventuali servizi a pagamento dopo la consegna. Non è solo burocrazia. Se la fatturazione resta sulla carta dell'agenzia, i servizi possono essere sospesi più tardi senza preavviso.

Un modo rapido per renderlo concreto:

• Nomina il proprietario dell'account per DNS, hosting e email
• Conferma chi paga ogni bolletta a partire dalla data di consegna
• Decidi se gli account vengono trasferiti o ricreati sotto il cliente
• Registra il contatto di supporto per ogni fornitore

Annota tutto in linguaggio semplice così entrambe le parti possono seguirlo.

Elenca gli ambienti e dove girano

Concorda quali ambienti esistono (local, staging, production) e dove ognuno gira. Nota se lo staging è un server separato, un database separato o solo un feature flag. Se hai usato una piattaforma come Koder.ai, conferma anche cosa è ospitato lì rispetto a cosa ci si aspetta che giri nell'infrastruttura del cliente dopo l'export.

Raccogli gli accessi in anticipo

Non aspettare l'ultimo giorno per richiedere gli accessi. Assicurati che le persone giuste possano raggiungere ciò di cui hanno bisogno: il repo, CI, hosting, il database e il provider email.

Concorda anche il test di accettazione finale e il processo di firma. Per esempio: “Il cliente può compilare da una macchina pulita, eseguire le migrazioni, distribuire su staging e passare lo smoke test. Poi entrambe le parti firmano per iscritto.”

Repo e documentazione di base da includere

Una buona checklist di consegna del codice sorgente inizia con un repo che un nuovo team può aprire e comprendere in pochi minuti. Conferma cosa è incluso (codice dell'app, template di configurazione, script) e cosa è intenzionalmente escluso (segreti reali, chiavi private, file generati di grandi dimensioni). Se qualcosa è escluso, indica dove risiede e chi ne è il proprietario.

Mantieni la struttura prevedibile. Punta a cartelle top-level chiare come frontend/, backend/, mobile/, infra/, scripts/ e docs/. Se il progetto è un monorepo, spiega come i pezzi si relazionano e come eseguire ciascuno di essi.

Il tuo README dovrebbe poter essere usato da qualcuno che non ha costruito il progetto. Deve coprire i prerequisiti e il percorso più veloce per avere un ambiente di sviluppo funzionante, senza supposizioni.

Cosa documentare (minimo)

Includi una breve sezione README che risponda a:

• Cosa contiene questo repo e cosa fa (un paragrafo)
• Prerequisiti con versioni esatte (runtime, package manager, Docker se necessario)
• I passi one-command per avviare lo sviluppo locale (e cosa significa “successo”)
• Come eseguire i test e creare un artefatto di produzione
• Dove trovare i documenti chiave: note architetturali, migrazioni, note di deployment

Aggiungi brevi note architetturali in linguaggio semplice: cosa comunica con cosa e perché. Un piccolo diagramma è opzionale, ma poche frasi sono solitamente sufficienti. Esempio: “Frontend React chiama l'API Go. L'API legge e scrive su PostgreSQL. I job in background girano come processo worker separato.”

Infine, includi un changelog o note di rilascio versionate per la build di consegna. Può essere un CHANGELOG.md o un breve file “handoff release notes” che indica l'esatto commit/tag, cosa è stato consegnato e problemi noti.

Se il codice è stato esportato da una piattaforma come Koder.ai, annota il tipo di progetto generato (web, server, mobile), la toolchain prevista (per esempio React, Go, PostgreSQL, Flutter) e le versioni di OS/tooling supportate che il cliente dovrebbe usare per riprodurre la build.

Variabili d'ambiente: inventario e documentazione

Le variabili d'ambiente sono spesso la ragione per cui un'app “funzionava” ma fallisce subito dopo la consegna. Una buona checklist tratta le variabili d'ambiente come parte del prodotto, non come un ripensamento.

Inizia scrivendo un inventario che un nuovo team possa seguire senza indovinare. Tienilo in linguaggio semplice e includi un esempio del formato del valore (non segreti reali). Se una variabile è opzionale, indica cosa succede quando manca e quale valore di default viene usato.

Un modo semplice di presentare l'inventario è:

• Nome della variabile, cosa controlla e un esempio di formato
• Richiesta vs opzionale, più eventuale comportamento di default
• Dove è impostata (CI, dashboard hosting, file .env locale)
• Quali ambienti richiedono valori diversi (dev, staging, production)
• Chi possiede le modifiche (cliente, agenzia o condiviso)

Evidenzia chiaramente le differenze per ambiente. Per esempio, lo staging può puntare a un DB di test e a un provider di pagamenti sandbox, mentre la production usa servizi live. Nota anche i valori che devono corrispondere tra sistemi, come callback URL, allowed origins o bundle identifier delle app mobile.

Documenta dove ogni valore risiede oggi. Molti team dividono i valori tra posti: file .env locali per lo sviluppo, variabili CI per le build e impostazioni hosting per il runtime. Se hai usato Koder.ai per esportare l'app, includi un file .env.example e una breve nota su quali variabili devono essere compilate prima della prima build.

Infine, dimostra che non ci sono segreti nascosti nel repo. Non limitarti a controllare i file correnti. Esamina la storia dei commit per chiavi accidentali, vecchi file .env o credenziali copiate in config di esempio.

Esempio concreto: un frontend React più un'API Go possono aver bisogno di API_BASE_URL per il web e di DATABASE_URL più JWT_SIGNING_KEY per il backend. Se lo staging usa un dominio diverso, scrivi entrambi i valori e indica dove cambiarli, così il nuovo team non deploya impostazioni di staging in produzione.

Rotazione dei segreti: trasferisci in sicurezza, poi verifica

La consegna non è completa finché il cliente non controlla ogni credenziale che l'app utilizza. Questo significa ruotare i segreti, non solo condividerli. Se un'agenzia (o un ex consulente) ha ancora chiavi funzionanti, rimane una porta aperta che non puoi auditare.

Inizia facendo un inventario completo. Non fermarti alle password del database. Includi chiavi API di terze parti, segreti client OAuth, segreti di firma webhook, chiavi di firma JWT, credenziali SMTP, chiavi di accesso allo storage e qualsiasi token “temporaneo” presente nella CI.

Ecco una semplice checklist per il giorno della rotazione:

• Elenca ogni segreto, cosa sblocca e dove è attualmente impostato (file env locali, CI, dashboard hosting, vault)
• Crea nuove credenziali negli account del cliente e assegna un proprietario per ognuna (una persona e una casella team)
• Aggiorna la configurazione dell'app per usare i nuovi valori, poi distribuisci prima in staging o in un ambiente di test
• Revoca le vecchie credenziali immediatamente dopo che quelle nuove sono confermate funzionanti
• Documenta esattamente i passaggi di rotazione così la prossima rotazione è noiosa e veloce

Dopo la rotazione, dimostra che nulla si è rotto. Esegui test rapidi “da utente reale” invece di controllare solo i log.

Concentrati sui flussi che dipendono dai segreti:

• Login, registrazione, reset password e refresh token
• Pagamenti, invio email e upload file
• Webhook (verifica firma e gestione retry)
• Job in background o attività pianificate che chiamano API esterne
• Azioni admin che colpiscono endpoint privilegiati

Esempio: se hai esportato un progetto da Koder.ai e l'app usa un provider di pagamenti più un servizio email, ruota entrambe le chiavi, ridistribuisci, poi effettua una piccola transazione di test e invia un'email di prova. Solo dopo che questi passaggi hanno successo revoca le chiavi dell'agenzia.

Infine, documenta dove risiederanno i segreti in futuro (vault, variabili CI o impostazioni hosting), chi può cambiarli e come tornare indietro in sicurezza se una rotazione causa errori.

Migrazioni database e gestione dei dati

Una consegna può sembrare “fatta” mentre il database è la prima parte che si rompe. Tratta migrazioni e dati come un prodotto a sé: versionati, ripetibili e testati.

Inizia annotando la versione corrente del database e dove risiedono le migrazioni nel repo. Sii specifico: il percorso della cartella, il pattern di naming e l'ultimo ID di migrazione (o timestamp). Se usi PostgreSQL (comune con backend Go), annota anche eventuali estensioni richieste.

Cosa documentare (così qualcun altro può eseguirlo)

Includi un breve runbook che risponda a queste domande:

• Quale comando esegue le migrazioni e in quale ordine eseguire le operazioni (crea database, applica migrazioni, poi seed)
• Come differisce per ambiente (local, staging, production), inclusi eventuali flag “safe mode”
• Se le migrazioni sono automatiche al deploy o devono essere eseguite manualmente, e chi è autorizzato a farlo
• Strategia dei dati seed: nessuno, demo-only o record minimi richiesti (utente admin, impostazioni di default)
• Piano di rollback: cosa può essere invertito e cosa no (per esempio, drop di colonne distruttive)

I rollback meritano onestà. Alcune modifiche sono reversibili solo con il ripristino di un backup. Indicalo in linguaggio semplice e abbinalo a un passo di backup (snapshot prima del deploy, verifica del processo di restore).

Prima che la consegna sia completa, esegui le migrazioni su una copia dei dati di produzione se possibile. Questo cattura query lente, indici mancanti e problemi del tipo “funziona su dati vuoti”. Un test realistico è esportare il codice, impostare le variabili d'ambiente, ripristinare un dump anonimizzato, poi applicare le migrazioni da zero. Quell'esercizio valida una grande parte di qualsiasi checklist di consegna.

Se l'app è stata costruita in una piattaforma come Koder.ai e poi esportata, ricontrolla che i file di migrazione e eventuali script di seed siano inclusi nell'export e ancora referenziati correttamente dal processo di avvio del backend.

Build e CI: rendilo ripetibile

Una consegna è completa solo quando qualcun altro può ricostruire l'app da zero su una macchina pulita. La checklist dovrebbe includere i comandi di build esatti, le versioni richieste e l'output atteso (per esempio: “bundle web in /dist”, “nome del binario API”, “posizione APK Flutter”).

Annota gli strumenti e i package manager che usi realmente, non quello che pensi di usare. Per uno stack tipico potrebbe essere Node.js (e npm o pnpm) per un'app React, la toolchain Go per il server, gli strumenti client PostgreSQL per il setup locale e l'SDK Flutter per il mobile.

Rendi le installazioni delle dipendenze prevedibili. Conferma che i lockfile siano committati (package-lock.json, pnpm-lock.yaml, go.sum, pubspec.lock) e fai una nuova installazione su un computer nuovo o in un container pulito per dimostrare che funziona.

Cattura cosa fa la CI, passo per passo, così può essere copiata su un altro provider CI se necessario:

• Installa le dipendenze (usando lockfile)
• Esegue test e lint
• Produce build (bundle web, binario server, build mobile)
• Genera artefatti (zip, immagine Docker, bundle di rilascio)
• Conserva log e metadati della build (versione, commit, data)

Separa la configurazione di build da quella di runtime. La config di build cambia ciò che viene compilato (come un API base URL incorporato in un bundle web). La config di runtime viene iniettata all'avvio (come URL del database, chiavi API e feature flag). Mischiare queste due è una ragione comune per cui “funziona in CI” ma fallisce dopo il deploy.

Fornisci una semplice ricetta di verifica locale. Anche pochi comandi sono sufficienti:

# Web
pnpm install
pnpm test
pnpm build

# API
go test ./...
go build ./cmd/server

# Mobile
flutter pub get
flutter test
flutter build apk

Se stai esportando da una piattaforma come Koder.ai, includi eventuali file CI generati o preset di build usati durante il deployment così il cliente può riprodurre la stessa build fuori dalla piattaforma.

Script di deployment e processo di rilascio

Una buona checklist di consegna non si ferma a “ecco il repo.” Spiega anche come l'app passa dal codice sorgente a un servizio in esecuzione e chi preme il pulsante.

Inizia annotando come avvengono oggi i deploy: completamente manuale (qualcuno esegue comandi su un server), guidato da CI (una pipeline costruisce e distribuisce) o tramite una piattaforma hostata. Includi dove risiedono le configurazioni e quali ambienti esistono (dev, staging, production).

Rendi i passaggi di rilascio ripetibili. Se il processo dipende da una persona che si ricorda 12 comandi, trasformali in script e annota i permessi necessari.

Cosa includere nel pacchetto di deployment

Dai al cliente abbastanza elementi per distribuire al giorno uno:

• Comandi di build e run (e versioni esatte di Node, Go, Flutter, ecc.)
• Script di deployment (script shell, target Makefile o config pipeline)
• Accessi richiesti: ruoli account cloud, registry di container, DNS, admin database
• Note di setup ambiente: dove sono impostate le env var e come differiscono per ambiente
• Nominazione delle release: tag/release e come identificare cosa è in esecuzione

Concorda le aspettative di downtime. Se è richiesto “zero downtime”, specifica cosa significa in pratica (blue-green, rolling deploy, finestra read-only per le migrazioni). Se il downtime è accettabile, definisci una finestra chiara.

Gli asset statici e le cache sono punti di fallimento comuni. Nota come gli asset sono costruiti e serviti, quando invalidare le cache e se è coinvolta una CDN.

Rollback che puoi davvero eseguire

Un rollback dovrebbe essere una ricetta breve e testata legata a un tag o ID di release. Per esempio: deploy del tag precedente, ripristino dell'ultimo snapshot del database se necessario e invalidazione delle cache.

Se l'app è stata creata su Koder.ai e poi esportata, menziona l'ultimo snapshot noto-buono e l'esatta versione di export così il cliente può associare il codice a una release funzionante rapidamente.

Passo-passo: verifica la build dopo l'export

La verifica è il momento in cui scopri se la consegna è reale. L'obiettivo è semplice: una persona nuova deve poter prendere il codice esportato, impostarlo e ottenere la stessa app funzionante senza tentativi.

Prima di iniziare, registra cosa significa “corretto”: la versione dell'app in esecuzione, il commit/tag corrente (se disponibile) e una o due schermate o risposte API chiave da confrontare. Se l'export proviene da una piattaforma come Koder.ai, annota lo snapshot o il timestamp dell'export così puoi dimostrare di aver testato lo stato più recente.

1. Conferma che l'export corrisponde alla produzione: controlla la storia dei commit, le note di rilascio o i metadati della build. Confronta una stringa di versione visibile o un piccolo comportamento (come un'impostazione o un'etichetta UI) con l'app in esecuzione.
2. Imposta variabili d'ambiente e segreti: crea la configurazione dell'ambiente target (locale e staging). Usa l'inventario delle env var fornito e assicurati che nulla sia hard-coded nel repo.
3. Installa dipendenze ed esegui i test: fai un'installazione pulita (senza cartelle node_modules/vendor in cache). Esegui i test unitari e eventuali lint esattamente come documentato.
4. Esegui migrazioni e avvia localmente: avvia il database, applica le migrazioni in ordine e avvia l'app. Conferma che l'app può leggere/scrivere dati di base e che non ci sono migrazioni in sospeso.
5. Distribuisci su staging, fai smoke test, poi promuovi: distribuisci usando gli stessi script/pipeline che prevedi per la produzione. Promuovi solo quando lo staging corrisponde alle aspettative.

Per gli smoke test, mantienili brevi e legati al rischio:

• Login/logout (o creare un utente di test)
• Un workflow core end-to-end (crea-modifica-salva)
• Una email/webhook/transazione di pagamento se applicabile
• Gestione errori di base (input errato, record mancante)
• I log non mostrano crash ripetuti o errori legati ai segreti

Se qualcosa fallisce, cattura il comando esatto, l'output d'errore e le env var usate. Quel dettaglio salva ore quando la proprietà cambia mani.

Errori comuni nella consegna e come evitarli

Il modo più rapido per trasformare una consegna in un incendio è presumere “il codice basta”. Una buona checklist si concentra sui piccoli dettagli noiosi che decidono se il cliente può davvero eseguire e modificare l'app senza di voi.

Gli errori che causano la maggior parte dei problemi

La maggior parte dei problemi rientra in pochi schemi ripetuti:

• I segreti non vengono ruotati, quindi password agenzia, chiavi API o token cloud funzionano ancora dopo la consegna.
• Le variabili d'ambiente sono incomplete perché alcuni valori risiedono solo in CI o nella dashboard hosting, non nel repo.
• Modifiche one-off in produzione vengono dimenticate, come un hotfix veloce, una modifica manuale al DB o un toggle di configurazione impostato direttamente sul server.
• Le migrazioni funzionano in locale ma falliscono in produzione a causa di permessi mancanti, estensioni o ownership dello schema.
• Non esiste un piano di rollback e non esiste una release taggata (o note di rilascio) a cui tornare quando il primo deploy va storto.

Come prevenirli (senza aggiungere settimane)

Rendi la rotazione e la pulizia degli accessi un'attività programmata, non un elemento “quando abbiamo tempo”. Fissa una data in cui gli account agenzia vengono rimossi, le chiavi di servizio rigenerate e il cliente conferma di poter distribuire usando solo le proprie credenziali.

Per le env var, fai un inventario semplice da tre posti: il repo, il sistema CI e l'interfaccia hosting. Poi convalida eseguendo una build pulita da una macchina o container nuovo.

Per le migrazioni, testa con lo stesso ruolo database che userà il deploy di produzione. Se la produzione richiede passaggi elevati (come abilitare un'estensione), documentali e rendine chiara la proprietà.

Un esempio realistico: dopo aver esportato un progetto da Koder.ai, il cliente deploya con successo ma i job in background falliscono perché un URL di coda era impostato solo nella dashboard hosting. Un rapido audit delle env var lo avrebbe evitato. Abbinalo a una release taggata e a un rollback documentato (per esempio, “redeploy tag v1.8.2 e ripristina l'ultimo snapshot”) e il team evita downtime.

Checklist finale, un esempio semplice e i prossimi passi

Se devi conservare solo una pagina da questa checklist, tieni questa. L'obiettivo è semplice: un clone pulito dovrebbe partire su una macchina nuova, con segreti nuovi e un database che può evolvere in sicurezza.

Controlli rapidi (esegui da un clone fresco)

Esegui questi controlli su un laptop che non ha mai visto il progetto (o in un container/VM pulito). È il modo più rapido per catturare file mancanti, assunzioni nascoste e credenziali vecchie.

• Costruisci da zero: installa dipendenze, esegui test (se presenti) e ottieni una build di rilascio senza modifiche manuali.
• La configurazione funziona: imposta le variabili d'ambiente documentate e conferma che l'app si avvia con un file di configurazione pulito o setup env.
• I segreti sono ruotati: verifica che l'app funzioni con le chiavi nuove, poi revoca quelle vecchie e conferma che nulla si rompe.
• Le migrazioni vengono eseguite pulite: parti da un database vuoto, esegui le migrazioni, poi avvia l'app e testa un flusso base.
• Il percorso di deployment è reale: esegui lo script di deploy o il workflow CI una volta e conferma che produce lo stesso output.

Un esempio semplice di consegna

Un'agenzia consegna un frontend React, un'API Go e un database PostgreSQL. Il team cliente clona il repo, copia il fornito .env.example nelle effettive env var e crea nuove credenziali per il database, il provider email e eventuali API di terze parti. Eseguono go test (o il comando di test concordato), compilano l'app React, applicano le migrazioni su una nuova istanza Postgres e avviano entrambi i servizi. Infine deployano usando lo script documentato e confermano che lo stesso commit può essere ricostruito in seguito.

Prossimi passi

Mantieni la consegna breve e con responsabilità chiare. Una walkthrough di 30-60 minuti spesso vale più di un documento lungo.

• Pianifica una walkthrough e registra le decisioni (chi possiede deploy, segreti e modifiche DB).
• Assegna un owner per l'accesso production e un backup.
• Concorda un commit hash di “acceptance build” finale e taggalo.
• Se hai costruito in Koder.ai, esporta il codice sorgente, poi usa snapshot e rollback durante il primo deploy eseguito dal cliente per ridurre il rischio.