Quando versionare un artefatto insieme al software

Scegliere dove deve vivere l'artefatto

Un artefatto trae beneficio dal vivere vicino al codice quando cambia con la stessa cadenza della soluzione, deve essere revisionato insieme all'implementazione, la storia delle modifiche è importante o può essere validato automaticamente. Il criterio non è imporre un unico luogo, ma evitare duplicazioni di autorità.

Criteri di scelta

• Deve cambiare nello stesso momento del codice?
• Una modifica dovrebbe accompagnare o bloccare una pull request?
• Esiste una forma verificabile o generabile automaticamente?
• Il pubblico principale lavora nel repository?
• La collaborazione visuale in tempo reale è parte essenziale del valore?

Repository, fonte strutturata o spazio collaborativo

• Repository: contratti API ed eventi, schema dati, configurazioni architetturali dichiarative, decision record e artefatti che devono seguire la delivery.
• Fonte strutturata con viste generate: utile quando si vuole versionare una sorgente autorevole e pubblicare rappresentazioni consumabili altrove.
• Spazio collaborativo: workshop, esplorazioni iniziali, mappe temporanee e materiali il cui valore principale è facilitare una conversazione.

Evitare il falso Architecture as Code

Se la stessa informazione esiste in repository, wiki e diagramma manuale, va dichiarato quale fonte è autorevole e quali viste sono derivate. Architecture as Code è utile quando riduce drift e aumenta verificabilità; diventa un anti-pattern quando trasforma ogni conversazione architetturale in manutenzione di file senza migliorare chiarezza o controllo.