Estabilidade da API¶
Django is committed to API stability and forwards-compatibility. In a nutshell, this means that code you develop against a version of Django will continue to work with future releases. You may need to make minor changes when upgrading the version of Django your project uses: see the “Backwards incompatible changes” section of the release note for the version or versions to which you are upgrading.
At the same time as making API stability a very high priority, Django is also committed to continual improvement, along with aiming for “one way to do it” (eventually) in the APIs we provide. This means that when we discover clearly superior ways to do things, we will deprecate and eventually remove the old ways. Our aim is to provide a modern, dependable web framework of the highest quality that encourages best practices in all projects that use it. By using incremental improvements, we try to avoid both stagnation and large breaking upgrades.
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..
We’ll only break backwards compatibility of these APIs without a deprecation process if a bug or security hole makes it completely unavoidable.
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.
