Stabilité de l’API¶
Django s’engage à fournir une API stable et une compatibilité ascendante. En résumé, cela signifie que le code que vous développez avec une version de Django continuera à fonctionner avec les publications futures. Il est parfois nécessaire d’effectuer de petits ajustements lors de la mise à niveau de la version de Django utilisée par votre projet : voir la section des « Changements incompatibles avec les version précédentes » des notes de publication concernant la ou les versions vers lesquelles vous mettez à niveau.
Tout en faisant de la stabilité de l’API une très haute priorité, Django s’engage également dans un processus d’amélioration continue et poursuit son objectif de donner (finalement) « une seule façon de faire les choses » dans l’API officielle. Cela signifie que lorsque nous découvrons des manières clairement supérieures de faire certaines choses, nous rendons osbolète, puis supprimons après un certain temps les anciennes manières de faire. Notre but est de fournir une infrastructure de développement Web moderne et fiable de la plus haute qualité qui encourage les bonnes pratiques dans tous les projets qui l’exploitent. En pratiquant des améliorations incrémentales, nous essayons à la fois d’éviter la stagnation et les grosses mises à jour exigeant des réécritures conséquentes.
Ce que « stable » signifie¶
Dans ce contexte, stable signifie :
Toutes les API publiques (tout ce qui est documenté) ne sera pas déplacé ni renommé sans mettre à disposition des alias rétrocompatibles.
Si de nouvelles fonctions sont ajoutées à ces API – ce qui est vraisemblable – elles ne vont pas casser ni modifier la signification des méthodes existantes. En d’autres termes, « stable » ne signifie pas forcément « complet ».
Si pour une raison ou une autre, une API déclarée stable doit être supprimée ou remplacée, elle sera déclarée obsolète mais restera dans l’API durant au moins deux publications principales. Des avertissements seront émis lors des appels aux méthodes obsolètes.
Voir Publications officielles pour plus de détails sur le schéma de numérotation des versions adopté par Django et sur le fonctionnement de la mise en obsolescence des fonctionnalités.
Nous ne casserons la rétrocompatibilité de ces API sans processus d’obsolescence que si un bogue ou une faille de sécurité le rend absolument inévitable.
API stables¶
En général, tout ce qui est couvert par la documentation, à l’exception de ce qui se trouve dans la zone de documentation interne, est considéré comme stable.
Exceptions¶
Il existe quelques exceptions à cet engagement de stabilité et de rétrocompatibilité.
Corrections de sécurité¶
Si un problème de sécurité vient à notre connaissance, si possible par quelqu’un respectant notre politique de signalement de problèmes de sécurité, nous ferons tout notre possible pour le corriger. Cela peut vouloir dire casser la rétrocompatibilité ; la sécurité passe avant la garantie de compatibilité.
API marquées comme internes¶
Certaines API sont explicitement déclarées « internes » par plusieurs moyens :
Certaines documentations se réfèrent à des éléments internes et le signalent explicitement. Si la documentation dit que quelque chose est interne, nous nous réservons le droit de le modifier.
Des fonctions, des méthodes et d’autres objets préfixés par un soulignement (
_). C’est la manière standard en Python d’indiquer que quelque chose est privé ; si une méthode commence par un_unique, il s’agit d’une API interne.
