Stabilità API

Django è votato alla stabilità delle API ed alla compatibilità futura. In poche parole, questo significa che il codice che sviluppi per una versione di Django continuerà a funzionare con le release future. Potresti avere bisogno di applicare alcuni piccoli cambiamenti quando aggiorni la versione di Django del tuo progetto: vedi la sezione «Modifiche non retrocompatibili» in release note relativa alla versione o alle versioni verso le quali stai aggiornando.

Pur essendo la stabilità delle API una priorità molto alta, Django è anche votato al miglioramento continuo, avendo congiuntamente l’obiettivo di illustrare (con il tempo) «un unico modo di fare le cose» nelle API che fornisce. Questo significa che quando troviamo un modo decisamente migliore di fare le cose, renderemo deprecati e rimuoveremo i vecchi modi di farle. Il nostro scopo è quello di fornire un web framework moderno ed affidabile che incoraggi le best practices in tutti i progetti che lo utilizzano. Con i miglioramenti incrementali, cerchiamo di evitare nello stesso modo la stagnazione ed i grandi breaking-upgrades.

Cosa significa «stabile»

In questo contesto, stabile significa:

• Tutte le API pubbliche (tutto in questa documentazione) non saranno spostate o rinominate senza fornire alias retro-compatibili.

• Se nuove caratteristiche sono aggiunte a queste API – che è del tutto possibile – non romperanno o cambieranno il significato dei metodi già esistenti. In altre parole, «stabile» non (necessariamente) significa «completo».

• Se, per qualche motivo, una API dichiarata stabile deve essere rimossa o sostituta, verrà definita come deprecata ma rimarrà tra le API per almeno due rilasci futuri. Si riceveranno degli avvertimenti quando si chiameranno i metodi deprecati.

  Controlla Official releases per maggiori dettagli su come funziona lo scema di numerazione delle versioni di Django, e come le features saranno deprecate.

• Interromperemo la retrocompatibilità di quelle API senza un processo di deprecazione se un bug oppure un problema di sicurezza lo rende completamente inevitabile.

API stabili

In generale, tutto quello che è coperto nella documentazione – ad eccezione di qualsiasi cosa si trovi nell’area internals area è da considerarsi stabile.

Eccezioni

Ci sono alcune eccezioni per questa promessa di stabilità e retrocompatibilità.

Fix di sicurezza

Se veniamo a conoscenza di un problema di sicurezza – magari da parte di chi segue la nostra :ref:` politica di security reporting <reporting-security-issues>` – faremo il necessario per sistemarlo. Questo potrebbe comportare il fatto di interrompere la retrocompatibilità; la sicurezza trionfa sulla garanzia di compatibilità.

API marchiate come internal

Alcune API sono esplicitamente marcate come «internal» in diversi modi :

• Alcune documentazioni si riferiscono agli internal e li menzionano come tali. Se nella documentazione qualcosa viene annotato come internal, ci riserviamo il diritto di cambiarlo.

• Funzioni, metodi e altri oggetti con il prefisso underscore (_). Questo è il modo standard di Python per indicare che qualcosa è privato; se qualsiasi metodo inizia con un singolo _, allora è una API internal.