Stabilité de l’API

Depuis la publication de Django 1.0, un engagement de stabilité d’API et de compatibilité ascendante a été pris. En résumé, cela signifie que le code que vous développez avec une version 1.x de Django continuera à fonctionner avec les publications 1.x 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 de versions mineures. 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.