django-autocomplete-light v4 et v5

django-autocomplete-light a deux lignes de versions actuelles avec des rôles différents : v4 existe pour fournir le chemin de mise à niveau documenté depuis v3 et à travers les versions Django prises en charge, tandis que v5 est l’endroit où nous pouvons prendre les ruptures de compatibilité arrière plus importantes qui débloquent la prochaine API.

Cet article clarifie à quoi sert chaque ligne, laquelle vous devriez installer, et où trouver la documentation de mise à niveau.

Version courte

Si vous utilisez déjà django-autocomplete-light 3.x en production, passez d’abord à v4.

La version 4 est la ligne de rupture la plus petite depuis v3. Elle garde l’intégration Select2 et la forme existante du projet, tout en ajoutant le support des versions modernes de Django. C’est la ligne de release à utiliser pendant que vous mettez un projet à niveau de Django 4.2 vers Django 5.2.

La version 5 est la ligne de rupture. Elle contient les changements qui n’auraient pas dû atterrir dans une release patch v4. Elle s’adresse aux projets prêts à adapter leurs personnalisations et à passer au cycle de vie plus propre, mais l’API v5 reste ouverte au changement si nous pouvons réduire la surface de rupture de compatibilité arrière.

Pourquoi v4 existe

Le but de v4 est volontairement ennuyeux : elle doit rendre les mises à niveau possibles sans forcer une réécriture d’application. Elle peut tout de même nécessiter des changements de code depuis v3, mais ces changements doivent être documentés et suffisamment limités pour que les projets puissent avancer progressivement.

En particulier, v4 est la ligne pour les projets qui ont besoin d’une version de django-autocomplete-light couvrant le chemin de mise à niveau Django LTS. Si votre application tourne encore sur Django 4.2 et que vous voulez atteindre Django 5.2, v4 est la ligne de release passerelle.

C’est important parce que les chemins de mise à niveau doivent être incrémentaux :

• mettre à niveau django-autocomplete-light de v3 vers v4 et gérer les changements v4 documentés,
• garder l’application fonctionnelle,
• puis mettre Django à niveau,
• puis envisager v5 quand vous êtes prêt pour ses ruptures.

Utilisez le guide de mise à niveau v3 vers v4 ici :

https://django-autocomplete-light.readthedocs.io/en/master/upgrade_from_v3_to_v4.html

Pourquoi v5 existe

La version 5 est l’endroit où doivent aller les changements incompatibles avec les versions précédentes.

Le point principal de v5 est de supprimer l’ancienne gestion du cycle de vie des objets côté jQuery du projet, et de simplifier la surface d’intégration Python et JavaScript pour la suite. C’est un travail utile, mais ce n’est pas un changement de niveau patch : les projets avec une initialisation JavaScript personnalisée, des widgets personnalisés ou des overrides Python peuvent devoir s’adapter.

Cela dit, v5 n’est pas une excuse pour casser plus que nécessaire. Nous sommes encore ouverts à changer l’API v5 avant qu’elle se stabilise si une autre forme préserve l’objectif tout en rendant les personnalisations existantes plus faciles à porter.

C’est particulièrement important pour les personnalisations avancées autour du rendu des options sélectionnées. Par exemple, certains projets utilisent to_field_name="uuid" ou filtrent les choix sélectionnés avec uuid__in au lieu de pk__in. Ces personnalisations ne devraient pas exiger de copier de gros blocs de code interne de widget, donc v5 est le bon endroit pour améliorer les points d’extension.

Utilisez le guide de mise à niveau v4 vers v5 ici :

https://django-autocomplete-light.readthedocs.io/en/master/upgrade_from_v4_to_v5.html

Compatibilité

Le point important est que v4 existe pour que les utilisateurs aient un chemin incrémental entre les versions Django LTS actuelles avant de prendre les plus gros changements de v5.

django-autocomplete-light 3.12.x

• Support Django : 4.2, 5.0, 5.1
• Support Python : 3.11-3.13
• Objectif : projets v3 existants avant la mise à niveau v4.

django-autocomplete-light 4.x

• Support Django : 4.2, 5.2
• Support Python : 3.11-3.14
• Objectif : ligne de release passerelle pour la mise à niveau v3 vers v4 et les mises à niveau Django 4.2 vers 5.2.

django-autocomplete-light 5.x

• Support Django : 5.2, 6.0+
• Support Python : 3.11-3.14
• Objectif : ligne de nettoyage pour les changements plus importants d’API et de cycle de vie.

Si vous mettez à niveau à la fois Django et django-autocomplete-light, le chemin prévu est de passer d’abord par v4. Ne sautez pas directement d’un vieux projet v3 vers v5 sauf si vous êtes prêt à gérer les deux étapes de mise à niveau en une seule fois.

Quelle version dois-je utiliser ?

Utilisez v4 si :

• vous mettez à niveau depuis django-autocomplete-light 3.x,
• vous avez besoin du plus petit chemin documenté depuis v3 à travers Django 4.2 et Django 5.2,
• vous dépendez du comportement Select2 existant,
• vous avez des personnalisations en production et voulez commencer par le plus petit changement.

Utilisez v5 si :

• vous démarrez un nouveau projet,
• vous avez déjà terminé la mise à niveau v4,
• vous êtes prêt à gérer des changements de personnalisation incompatibles avec les versions précédentes,
• vous voulez tester la nouvelle API et aider à réduire la surface finale de rupture,
• vous voulez le cycle de vie plus propre et la direction future de l’API.

À propos de la confusion de release

Un changement incompatible avec les versions précédentes a été publié comme 4.0.1. C’était une erreur. Il a été déplacé vers la ligne v5 afin que les projets épinglés à v4 puissent rester sur le chemin de compatibilité.

La ligne v4 est maintenant l’endroit pour le plus petit chemin de mise à niveau v3 vers v4 et les correctifs de compatibilité, y compris le support de Django 4. La ligne v5 est l’endroit pour les grandes ruptures intentionnelles.

À l’avenir, la règle est simple :

• v4 est pour le chemin de mise à niveau v3 documenté et le pont de mise à niveau Django,
• v5 est pour les ruptures plus importantes et le nettoyage,
• la documentation de release doit dire quelles versions de Django sont prises en charge,
• les releases de package devraient être yanked plutôt que supprimées quand c’est possible, afin que les déploiements épinglés échouent moins mystérieusement.

Si une release casse vos builds de façon inattendue, gardez en tête que mon numéro de téléphone est présent dans le footer de ce blog/site. Le README de django-autocomplete-light a aussi une section pour aider les gens à me joindre rapidement dans cette situation. Je veux vraiment le savoir dès que possible quand une release casse des chemins de mise à niveau en production, parce que c’est le moment où un yank rapide, un patch ou une clarification peut faire gagner beaucoup de temps à beaucoup de monde.

Documentation

Les pages de mise à niveau sont :

• Upgrade from v3 to v4
• Upgrade from v4 to v5

Le tableau de compatibilité est documenté ici :

https://django-autocomplete-light.readthedocs.io/en/master/#compatibility

Si quelque chose dans le chemin de mise à niveau reste flou, ouvrez une issue avec les versions de Django et django-autocomplete-light que vous utilisez, les versions cibles, et toute personnalisation de widget ou JavaScript impliquée. Pour v5 en particulier, les exemples de personnalisations devenues plus dures que nécessaire sont utiles : nous pouvons encore changer l’API si cela réduit le chemin de mise à niveau.