# Versioni e compatibilità

> Cosa cambia in /v1 senza preavviso, cosa è annunciato 30 giorni prima, e dove seguire le novità.

URL: https://developers.vimine.network/guides/versioning/

L'API ha la versione nel percorso, `/v1`, e una data: quella del documento OpenAPI (`info.version`), il giorno della
sua ultima modifica. Ogni modifica ha la sua voce nelle [Novità](https://developers.vimine.network/news/).

## Le modifiche compatibili

Arrivano in `/v1` quando sono pronte, con la loro voce lo stesso giorno:

- un nuovo endpoint, un nuovo campo in una risposta, un nuovo parametro o campo facoltativo in una richiesta;
- un nuovo valore di una stringa che il riferimento descrive come aperta (come `payment.method`) e un nuovo `code` di
  errore;
- un nuovo permesso (scope) e una nuova lingua.

Perché nessuna rompa la tua integrazione: ignora i campi che non conosci, tratta un valore sconosciuto di una stringa
aperta come un caso generico, e prevedi un ramo per i `code` di errore che non gestisci uno per uno.

Le pagine di Vimine (l'accesso, il modulo di adesione, l'agenda) possono cambiare aspetto in ogni momento; i loro
indirizzi e i parametri che accettano seguono le stesse regole dell'API.

## Le modifiche che chiedono un intervento

Un campo tolto o rinominato, un parametro che diventa obbligatorio, una risposta che cambia significato: una modifica
così è annunciata almeno **30 giorni** prima di arrivare, con una voce *Azione richiesta* che dice cosa cambiare ed
entro quando, e con una mail a chi ha un account sviluppatore e a chi guida un'associazione con un'app attiva. Quando
arriva, una seconda voce lo dice.

Durante la beta una modifica così arriva in `/v1`. Dopo la beta arriverà in una nuova versione, `/v2`, accanto a `/v1`
per almeno sei mesi.

## L'SDK e il plugin WordPress

- `@vimine/sdk`: finché la versione è 0.x, una patch (0.3.6) non chiede mai di cambiare il tuo codice; una versione
  minore (0.4.0) può farlo, e la sua voce dice cosa. Le voci sono anche nel pacchetto, in `CHANGELOG.md`.
- Il plugin WordPress si aggiorna da WordPress.org, dove la sua scheda riporta le stesse voci.

## Seguire le novità

- La pagina [Novità](https://developers.vimine.network/news/) e il suo feed Atom, in ogni lingua del portale: `/news.xml` in italiano, `/en/news.xml`
  in inglese, e così via.
- Nella console di Vimine, **Sviluppatori** mostra le ultime voci.
- Le voci *Azione richiesta* arrivano anche per mail.