Estabilidade da API

O Django garante uma API estável e com compatibilidade futura desde a versão 1.0. Resumindo, isto significa que o código que você desenvolver em uma versão do Django continuará a funcionar em versões futuras. Você poderá precisar fazer pequenas alterações ao atualizar a versão de Django utilizada em seu projeto: veja a seção “Mudanças incompatíveis com versões anteriores” no release note da versão ou das versões para as quais você está atualizando.

O que “estável” significa

Neste contexto, estável significa:

• Todas as APIs públicas (tudo nesta documentação) não serão retiradas ou renomeadas sem fornecer aliases para compatibilidade com as versões anteriores.

• Se novas funcionalidades forem adicionadas a estas APIs – o que é bem possível – elas não quebrarão ou alterarão o significado de métodos já existentes. En outras palavras, “estável” não significa (necessariamente) “completo”.

• Se, por alguma razão, uma API declarada estável deva ser removida ou substituída, ela será declarada como obsoleta, mas continuará na API ao menos durante duas versões futuras. Mensagens de aviso serão geradas quando métodos marcados como obsoletos são usados.

  Veja Releases oficiais para mais informações sobre como a numeração de versão do Django funciona e como funcionalidades serão marcadas como obsoletas..

• Nós só quebraremos a compatibilidade com versões anteriores das APIs se um bug ou falha de segurança torne este fato completamente impossível de evitar.

APIs Estáveis

Em geral, tudo coberto na documentação – com exceção de tudo em internals area é considerado como estável.

Exceções

Existem poucas exceções a esta garantia de estabilidade e compatibilidade com versões anteriores.

Correções de segurança

Se nós tomarmos conhecimento de um problema de segurança – com sorte feita por alguém que siga nossa Política de Comunicação de Segurança – nós faremos todo o necessário para resolvê-lo. Isto pode significar quebrar a compatibilidade com versões anteriores; segurança acima da garantia de compatibilidade.

API’s marcadas como internas

Certas APIs são explicitamente marcadas como “internas” de algumas maneiras:

• Alguma documentação refere-se a detalhes de implementação de uso interno e os menciona como tal. Se alguma documentação diz que algo é para uso interno, nós nos damos o direito de alterá-lo.

• Funções, métodos e outros objetos prefixados por um sublinha (_). Esta é a forma padrão em Python para indicar que algo é privado; se algum nome de método começar com um único _ é uma API interna.