Estabilidade da API¶
O Django está comprometido com a estabilidade da API e compatibilidade com versões futuras. Resumindo, isso significa que o código que você desenvolve em uma versão do Django continuará a funcionar com versões futuras. Você pode precisar fazer pequenas alterações ao atualizar a versão do Django que seu projeto usa: veja a seção “Alterações incompatíveis com versões anteriores” da nota de lançamento para a versão ou versões para as quais você está atualizando.
Ao mesmo tempo em que torna a estabilidade da API uma prioridade muito alta, o Django também está comprometido com a melhoria contínua, juntamente com o objetivo de “uma maneira de fazer isso” (eventualmente) nas APIs que fornecemos. Isso significa que, quando descobrimos maneiras claramente superiores de fazer as coisas, descontinuamos e, eventualmente, removeremos as maneiras antigas. Nosso objetivo é fornecer um framework web moderno e confiável da mais alta qualidade que incentive as melhores práticas em todos os projetos que a utilizam. Usando melhorias incrementais, tentamos evitar a estagnação e grandes atualizações de interrupção.
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..
Só quebraremos a compatibilidade retroativa dessas APIs sem um processo de depreciação se um bug ou falha de segurança o tornar completamente inevitável.
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.
