Stabilité de l’API¶
Django s’engage à garantir une API stable et une compatibilité ascendante depuis la version 1.0. 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.
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 Official releases 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 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.
