Passa al contenuto principale

Politica di compatibilità

A partire dalla versione 1.0.0, Canopy si impegna a garantire una compatibilità con le versioni precedenti documentata all'interno di una linea di versione maggiore. Questa pagina è il contratto: descrive cosa rimane stabile, cosa può cambiare e come funzionano le deprecazioni, in modo che gli operatori possano pianificare gli aggiornamenti senza sorprese.

La politica si applica a 1.x. Una futura linea 2.x potrebbe rivederla; in tal caso, una guida alla migrazione verrà pubblicata insieme alle note di rilascio di 2.0.0.

Cosa è coperto​

Schema del database (migrazioni Alembic)​

All'interno di 1.x:

  • Le migrazioni sono additive o compatibili con le versioni precedenti all'aggiornamento.
  • Nuove colonne possono essere aggiunte in qualsiasi momento.
  • Le colonne esistenti non verranno eliminate senza passare attraverso un ciclo di deprecazione.
  • Le colonne esistenti non verranno rinominate senza un ciclo di deprecazione (un cambio di nome viene implementato come aggiungi-nuova-colonna → backfill → depreca-colonna-vecchia → elimina-nella-prossima-maggiore).
  • Le modifiche al tipo sono limitate all'ampliamento (ad es. varchar(80) → varchar(255)); le modifiche di riduzione passano attraverso la deprecazione.
  • I vincoli di chiave esterna non diventeranno più restrittivi (ad es. ON DELETE SET NULL che diventa ON DELETE CASCADE) senza un ciclo di deprecazione.

Gli operatori possono aggiornare con fiducia; la migrazione automatica all'avvio del backend è sicura da eseguire sui dati di produzione.

Metamodello integrato​

All'interno di 1.x, il metamodello distribuito in backend/app/services/seed.py è stabile:

  • Le chiavi dei tipi di scheda integrati (Application, Initiative, BusinessCapability, ecc.) non verranno rinominate o rimosse.
  • Le chiavi di campo integrate su quei tipi non verranno rimosse senza un ciclo di deprecazione.
  • Le chiavi dei tipi di relazione integrati non verranno rinominate o rimosse senza un ciclo di deprecazione.
  • I sottotipi predefiniti distribuiti con i tipi integrati sono stabili.

Le personalizzazioni degli operatori (tipi di scheda personalizzati, campi personalizzati aggiunti tramite l'interfaccia di amministrazione, tipi di relazione personalizzati) sono di proprietà dell'operatore e non sono coperti da questa politica.

API REST (/api/v1/)​

All'interno di 1.x:

  • Gli endpoint sotto /api/v1/ non verranno rimossi senza un ciclo di deprecazione.
  • I nomi dei campi di richiesta e risposta esistenti non verranno rinominati senza un ciclo di deprecazione.
  • I tipi di campo non cambieranno in modo incompatibile (ad es. stringa → array).
  • I nuovi campi di richiesta opzionali e i nuovi campi di risposta non sono modifiche incompatibili e possono essere introdotti in qualsiasi versione minore.
  • I nuovi endpoint non sono modifiche incompatibili e possono essere introdotti in qualsiasi versione minore.
  • La semantica di autenticazione (JWT Bearer, la forma del payload di /auth/login) è stabile.
  • La semantica dei codici di stato HTTP è stabile per i percorsi di successo ed errore documentati.

Il comportamento al di là della superficie documentata (intestazioni non documentate, testo dei messaggi di errore interni, ordinamento quando non è specificato sort_by) non è coperto.

Chiavi di permesso​

Le chiavi di permesso definite in backend/app/core/permissions.py sono stabili all'interno di 1.x. Nuove chiavi possono essere aggiunte; le chiavi esistenti non verranno rinominate o rimosse senza un ciclo di deprecazione.

L'insieme dei permessi concessi per impostazione predefinita ai ruoli predefiniti (admin, bpm_admin, member, viewer) può cambiare tra versioni minori, con una nota nel CHANGELOG. Gli operatori che hanno personalizzato i permessi dei ruoli nella propria distribuzione non sono interessati.

Configurazione (variabili di ambiente)​

Le variabili di ambiente esistenti documentate in CLAUDE.md e README.md sono stabili all'interno di 1.x. Nuove variabili possono essere aggiunte con valori predefiniti ragionevoli. I valori predefiniti possono cambiare con una nota nel CHANGELOG quando la modifica è rilevante per l'operatore (ad es. una nuova porta predefinita).

Segreti cifrati a riposo​

Il marcatore di prefisso enc: e la chiave derivata da Fernet in backend/app/core/encryption.py sono stabili all'interno di 1.x. Gli operatori non hanno bisogno di ri-cifrare i segreti tra aggiornamenti minori.

Ciclo di deprecazione​

Quando qualcosa coperto da questa politica deve essere rimosso:

  1. Contrassegnare come deprecato nella versione minore N. La voce del CHANGELOG include una sezione Deprecated che descrive la modifica. Per gli endpoint API, la rotta deprecata emette un'intestazione di risposta Deprecation: true (RFC 8594) e un'intestazione Sunset che indica l'obiettivo di rimozione più precoce.
  2. Continuare a supportare nella versione minore N+1. La rimozione non può avvenire nella stessa versione minore della deprecazione. La forma deprecata continua a funzionare.
  3. Rimozione più precoce nella versione minore N+2 o in 2.0 (a seconda di quale arriva prima). La rimozione avviene con una sezione Removed nel CHANGELOG e una nota di migrazione.

Per le modifiche alla forma dei dati (migrazioni Alembic), si applica la stessa cadenza N → N+1, espressa come aggiungi-nuovo → backfill → elimina-vecchio.

Cosa non è coperto​

Questi elementi sono esplicitamente fuori ambito e possono cambiare in qualsiasi momento:

  • La struttura interna dei moduli Python sotto backend/app/. Le importazioni di app.models, app.services, ecc. non fanno parte dell'API pubblica. I plugin o gli script che dipendono da importazioni interne devono fissare una versione specifica di Canopy.
  • La struttura dei blob JSONB memorizzati nelle tabelle integrate (fields_schema, section_config, attributes, lifecycle) al di là di ciò che viene letto dall'API REST documentata. La forma JSON su disco può evolversi per supportare nuove funzionalità.
  • Componenti interni del frontend: percorsi dei file dei componenti, firme delle proprietà dei componenti in frontend/src/, il contenuto di frontend/src/types/index.ts e lo stile dei componenti MUI. Gli operatori che utilizzano il frontend incluso sono protetti; chiunque incorpori componenti dall'albero sorgente lo fa a proprio rischio.
  • Personalizzazioni del metamodello introdotte dagli operatori. Se si aggiunge un tipo di scheda o un campo personalizzato tramite l'interfaccia di amministrazione, si è responsabili della storia di migrazione quando lo si modifica.
  • Dati dimostrativi e di seed (SEED_DEMO=true). Il dataset dimostrativo può evolversi liberamente tra i rilasci.
  • Servizi di terze parti inclusi: versione DrawIO, immagine Ollama inclusa, versione swagger-ui-dist incorporata. Questi possono essere aggiornati in qualsiasi momento.
  • Comportamento con configurazioni non predefinite che sono esplicitamente contrassegnate come sperimentali nelle voci del CHANGELOG.

Cosa cambia effettivamente con «1.0.0»​

Rispetto alla serie 0.x, 1.0.0 in sé non è un rilascio di funzionalità — è il punto in cui iniziano ad applicarsi gli impegni sopra descritti. Il codice distribuito in 1.0.0 è lo stesso distribuito in 0.71.0, più il rafforzamento della catena di fornitura e le modifiche al flusso dei collaboratori documentate nella voce del CHANGELOG di 1.0.0.

I rilasci precedenti a 1.0 non erano coperti da questa politica. Le migrazioni tra versioni 0.x potevano e includevano eliminazioni di schemi, rinominazioni e modifiche incompatibili al metamodello. A partire da 1.0.0, tali modifiche passano attraverso il ciclo di deprecazione.