Versionare strumenti e schemi

Quando altri si connettono, fanno affidamento sui nomi degli strumenti e sulle forme degli argomenti. Modificarli senza cautela interrompe tutti i client contemporaneamente.

Aggiungere un parametro facoltativo con un valore predefinito mantiene operativi i vecchi chiamanti. Semplicemente ignorano il nuovo campo che non inviano.

Rinominare uno strumento, rimuovere un argomento o renderne uno obbligatorio è una modifica incompatibile. I client esistenti inviano improvvisamente chiamate che non sono più conformi.

Per far evolvere un campo, aggiunga quello nuovo e mantenga quello precedente. Indichi quello precedente come deprecato nella descrizione, così chi effettua le chiamate saprà che deve eseguire la migrazione.

In caso di una vera modifica incompatibile, distribuisca uno strumento v2 accanto a v1. Entrambi funzioneranno per un certo periodo, consentendo ai client di migrare secondo i propri tempi.

Durante l'handshake, il server comunica un nome e una versione. Incrementi la versione, così i client possono sapere a quale release si sono connessi.

Utilizzi semver: incrementi la patch per le correzioni, la minor per le funzionalità aggiuntive e la major quando apporta una modifica incompatibile. Il numero racconta una storia.

Aggiungere un campo a un risultato è generalmente sicuro; rimuoverne uno è una modifica incompatibile. Consideri lo schema di output come una promessa che i client analizzano.

Registri ogni modifica agli strumenti e agli schemi in un changelog. Chi esegue l'aggiornamento deve poter vedere cosa è cambiato, cosa è nuovo e cosa è stato rimosso.

Comunichi quando uno strumento precedente verrà rimosso. Una data di sunset chiara incentiva la migrazione senza cogliere nessuno alla sprovvista.

Prima del rilascio, esegua i test simulando le chiamate di un client precedente. In questo modo individuerà le modifiche incompatibili accidentali che il type checker non può rilevare.

Preferisca modifiche additive, deprechi prima di rimuovere, distribuisca v2 per le vere modifiche incompatibili, segua semver e mantenga un changelog. Potrà distribuire con fiducia! 🚀