Intéressé à redonner un peu de votre temps à la communauté ? Vous avez peut-être trouvé un bogue dans Django et vous souhaiteriez le corriger, ou alors vous aimeriez ajouter une petite fonctionnalité dans Django.
\nLa meilleure manière de réaliser ces objectifs est de contribuer à Django lui-même. Si cela peut paraître une tâche effrayante au premier abord, ce n’est finalement pas si difficile que cela. Nous allons vous accompagner tout au long de ce processus afin que vous puissiez apprendre avec un exemple.
\nPour ce tutoriel, il s’agit d’avoir au moins une compréhension générale de la manière dont Django fonctionne. Cela implique que vous devez être à l’aise en parcourant les tutoriaux existants sur l”écriture de votre première application Django. De plus, vous devriez bien connaître Python lui-même. Si ce n’est pas le cas, Dive Into Python est un livre en ligne fantastique (et gratuit) pour les programmeurs Python débutants.
\nCeux d’entre vous qui ne sont pas familiers avec les systèmes de gestion de versions et avec Trac trouveront dans ce tutoriel et ses liens les bonnes informations pour bien démarrer. Toutefois, il serait souhaitable d’en apprendre un peu plus sur ces différents outils si vous pensez contribuer régulièrement à Django.
\nMais pour la plus grande partie, ce tutoriel vise à expliquer le plus possible de choses pour qu’il puisse convenir au plus grand nombre.
\n\nNous allons vous guider dans votre première contribution d’un correctif pour Django. À la fin de ce tutoriel, vous aurez acquis une compréhension basique à la fois des outils et des processus nécessaires. Plus particulièrement, nous aborderons les thèmes suivants :
\ninstallation de Git,
le téléchargement d’une copie de développement de Django,
le lancement de la suite de tests de Django,
l’écriture d’un test pour votre correctif,
l’écriture du code du correctif,
le test de votre correctif,
la soumission d’une requête de contribution,
les sources d’informations supplémentaires.
Une fois le tutoriel terminé, vous pouvez consulter le reste de la documentation de Django sur la façon de contribuer. Elle contient de nombreuses informations utiles et constitue une lecture indispensable pour tout contributeur en herbe à Django. Si vous avez des questions, vous y trouverez probablement les réponses.
\n\n\nEn tant que contributeur, vous pouvez nous aider à maintenir la communauté Django ouverte et accueillante. Lisez et respectez notre Code de conduite.
\nPour ce tutoriel, Git doit être installé afin de pouvoir télécharger la version actuelle de développement de Django et pour générer les fichiers correctifs contenant vos modifications.
\nPour savoir si Git est installé, saisissez git sur une ligne de commande. Si vous obtenez un message vous indiquant que la commande n’a pas pu être trouvée, c’est que vous devez l’installer, voir la page de téléchargement de Git.
Si vous ne connaissez pas bien Git, vous pouvez toujours obtenir des informations sur les commandes (une fois installé) en tapant git help sur une ligne de commande.
La première étape pour contribuer à Django est d’obtenir une copie de son code source. Commencez par créer un fork de Django sur GitHub. Puis, à partir de la ligne de commande, utilisez la commande cd pour vous placer dans le répertoire où vous souhaitez mettre votre copie locale de Django.
Téléchargez le dépôt du code source de Django en utilisant la commande suivante :
\n$ git clone git@github.com:YourGitHubName/django.git\nMaintenant que vous disposez d’une copie locale de Django, vous pouvez l’installer comme tout autre paquet à l’aide de pip. La façon la plus simple de le faire est d’utiliser un environnement virtuel (ou virtualenv) qui est une fonctionnalité de Python permettant d’isoler dans une répertoire dédié les paquets installés pour chacun de vos projets afin qu’ils n’interfèrent pas entre eux.
Il est conseillé de conserver tous les environnements virtuels au même endroit, par exemple dans .virtualenvs/ dans votre dossier personnel. Créez-le s’il n’existe pas encore :
$ mkdir ~/.virtualenvs\nCréez maintenant un nouveau virtualenv en exécutant :
\n$ python3 -m venv ~/.virtualenvs/djangodev\nLe chemin correspond à l’endroit où le nouvel environnement sera enregistré sur votre ordinateur.
\n\n\nLa dernière étape de préparation de l’environnement virtuel est de l’activer :
\n$ source ~/.virtualenvs/djangodev/bin/activate\nSi la commande source n’est pas disponible, vous pouvez essayer d’utiliser un point à la place :
$ . ~/.virtualenvs/djangodev/bin/activate\nVous devez activer le virtualenv chaque fois que vous ouvrez une nouvelle fenêtre de terminal. virtualenvwrapper est un outil utile pour rendre cette opération plus directe.
\nÀ partir de cet instant, tout ce que vous installez avec pip sera installé dans votre nouvel environnement virtuel, isolé des autres environnements et des paquets du système. De plus, le nom de l’environnement actuellement actif est affiché sur la ligne de commande pour vous aider à voir d’un coup d’un coup d’œil lequel est activé. Poursuivez en installant la copie de Django précédemment chargée :
$ pip install -e /path/to/your/local/clone/django/\nLa version installée de Django correspond maintenant à votre copie locale. Vous constaterez immédiatement les effets de toute modification, ce qui est très utile lorsqu’on se met à écrire des correctifs.
\nPour ce tutoriel, nous allons utiliser le ticket #24788 comme étude de cas ; nous allons donc revenir en arrière dans l’historique Git de Django jusqu’au point où le correctif de ce ticket n’était pas encore appliqué. Cela nous permettra de parcourir toutes les étapes nécessaires à l’écriture de ce correctif à partir de zéro, y compris en lançant la suite de tests de Django.
\nGardez à l’esprit que même si nous allons utiliser une révision plus ancienne de Django dans l’optique de ce tutoriel, vous devriez toujours utiliser la révision la plus actuelle du développement de Django lorsque vous travaillez sur le correctif réel d’un ticket !
\n\nPlacez-vous dans le répertoire racine de Django (celui qui contient django`, docs, tests, AUTHORS, etc.). Vous pouvez ensuite extraire l’ancienne révision de Django qui nous sera utile pour le tutoriel ci-dessous :
$ git checkout 4ccfc4439a7add24f8db4ef3960d02ef8ae09887\nEn contribuant à Django, il est très important que vos modifications de code n’introduisent pas de bogues dans d’autres parties de Django. Une des façons de contrôler que Django fonctionne toujours après vos modifications est de lancer la suite de tests de Django. Si tous les tests passent, il est raisonnable de penser que vous n’avez pas complètement cassé Django. Si vous n’avez encore jamais lancé la suite de tests de Django, il est recommandé de le faire une fois simplement pour vous familiariser avec ce que l’on obtient d’habitude quand tout va bien.
\nAvant de lancer la suite de tests, installez ses dépendances en vous plaçant d’abord dans le répertoire tests/ de Django et en exécutant :
$ pip install -r requirements/py3.txt\nSi vous rencontrez une erreur durant l’installation, il est possible qu’une dépendance pour un ou plusieurs paquets Python manque sur votre système. Consultez la documentation du paquet problématique ou recherchez sur le Web avec le message d’erreur obtenu.
\nNous sommes maintenant prêts à lancer la suite de tests. Si vous utilisez GNU/Linux, macOS ou une autre version de Unix, lancez :
\n$ ./runtests.py\nMaintenant prenez place et détendez-vous. La suite complète de tests Django contient plus de 9600 tests différents, ce qui peut prendre entre 5 et 15 minutes en fonction de la rapidité de votre ordinateur.
\nPendant que la suite de tests de Django s’exécute, vous voyez un flux de caractères représentant le statut de chaque test exécuté. E indique qu’une erreur est survenue durant le test et F indique qu’une assertion de test a échoué. Les deux sont considérés comme des échecs. Quant à eux, x et s indiquent respectivement des échecs attendus et des tests omis volontairement. Chaque point signifie qu’un test a réussi.
Les tests omis volontairement sont typiquement dus à des bibliothèques externes manquantes et nécessaires pour exécuter ces tests ; voir Running all the tests pour une liste de dépendances. Prenez soin d’installer toute dépendance de test qui est liée aux modifications que vous appliquez (nous n’en utiliserons pas pour ce tutoriel). Certains tests sont spécifiques à un moteur de base de données particulier et seront sautés lors des tests avec les autres moteurs. SQLite est le moteur de base de données des réglages par défaut. Pour lancer les tests avec un moteur différent, consultez Using another settings module.
\nLorsque les tests sont terminés, vous devez voir apparaître un message vous informant si la suite de tests a réussi ou échoué. Comme vous n’avez encore pas modifié de code Django, toute la suite de tests devrait passer. Si vous obtenez des échecs ou des erreurs, vérifiez que vous avez bien suivi toutes les précédentes étapes. Consultez Running the unit tests pour plus d’informations. Si vous utilisez Python 3.5+, il y aura quelques échecs en lien avec des avertissements d’obsolescence que vous pourrez ignorer. Ces échecs ont été corrigés depuis dans Django.
\nIl faut savoir que la version « trunk » (la plus actuelle) de Django n’est pas toujours stable. Lorsque vous développez sur cette version, vous pouvez vérifier les compilations d’intégration continue de Django pour savoir si les échecs que vous obtenez sont spécifiques à votre environnement ou s’ils sont aussi présents dans les compilations officielles de Django. Si vous cliquez sur une compilation particulière, vous voyez la « matrice de configurations » qui indique les échecs précisément par version de Python et par moteur de base de données.
\n\nAvant toute modification, créez une nouvelle branche pour le ticket :
\n$ git checkout -b ticket_24788\nVous êtes libre de choisir le nom de la branche, « ticket_24788 » est un exemple. Toutes les modifications appliquées dans cette branche seront spécifiques au ticket et ne toucheront pas la copie principale du code que nous avons clonée précédemment.
\nDans la majorité des cas, un correctif doit contenir des tests pour être accepté dans Django. Pour les correctifs de correction de bogue, cela implique la rédaction d’une test de régression pour s’assurer que le bogue ne soit plus réintroduit plus tard dans Django. Un test de régression doit être écrit de façon à échouer tant que le bogue est présent et à réussir lorsque le bogue a été corrigé. En ce qui concerne les correctifs contenant de nouvelles fonctionnalités, vous devrez inclure des tests qui assurent que les nouvelles fonctionnalités fonctionnent correctement. Ces tests devraient aussi échouer avant que la fonctionnalité ne soit développée, et réussir après qu’elle a été implémentée.
\nUne bonne manière de faire cela est d’écrire d’abord les nouveaux tests, avant de toucher au code. Ce style de développement est appelé développement piloté par les tests et peut être appliqué aussi bien à des projets complets qu’à des correctifs individuels. Après avoir écrit les tests, vous les lancez pour être sûr qu’ils échouent effectivement (puisque vous n’avez pas encore corrigé l’erreur ou ajouté la fonctionnalité). Si vos nouveaux tests n’échouent pas, vous devez les corriger jusqu’à ce qu’ils échouent. Après tout, un test de régression qui passe que le bogue soit présent ou non n’est pas très utile pour éviter que ce bogue ne réapparaisse à l’avenir.
\nEntrons maintenant dans le vif du sujet.
\nLe ticket #24788 propose l’ajout d’une petite fonctionnalité : la possibilité de définir l’attribut de classe prefix pour les classes de formulaires, afin que :
[…] forms which ship with apps could effectively namespace themselves such\nthat N overlapping form fields could be POSTed at once and resolved to the\ncorrect form.\nDans le but de résoudre ce ticket, nous allons ajouter un attribut prefix à la classe BaseForm. Lors de la création d’instances de cette classe, la transmission d’un préfixe à la méthode __init__() va toujours définir ce préfixe pour l’instance créée. Mais si aucun préfixe n’est transmis (ou None), c’est le préfixe de classe qui sera utilisé. Cependant, avant d’effectuer ces changements, nous allons écrire quelques tests pour vérifier que notre modification fonctionne et qu’elle continue à fonctionner correctement à l’avenir.
Placez-vous dans le dossier tests/forms_tests/tests/ et ouvrez le fichier test_forms.py. Ajoutez le code suivant à la ligne 1674, juste avant la fonction test_forms_with_null_boolean:
def test_class_prefix(self):\n # Prefix can be also specified at the class level.\n class Person(Form):\n first_name = CharField()\n prefix = 'foo'\n\n p = Person()\n self.assertEqual(p.prefix, 'foo')\n\n p = Person(prefix='bar')\n self.assertEqual(p.prefix, 'bar')\nCe nouveau test contrôle que la définition d’un préfixe au niveau de la classe fonctionne comme attendu et que la transmission d’un paramètre prefix au moment de la création d’une instance continue aussi de fonctionner.
Rappelez-vous que nous n’avons encore effectué aucune modification à BaseForm, ce qui fait que nos tests vont échouer. Lançons tous les tests dans le dossier forms_tests pour être certain que c’est vraiment ce qui va se passer. À partir de la ligne de commande, placez-vous dans le répertoire tests/ de Django et lancez :
$ ./runtests.py forms_tests\nSi les tests se sont déroulés correctement, vous devriez voir un échec correspondant à la méthode de test que nous avons ajoutée. Si tous les tests ont réussi, vous devriez alors vérifier que vous avez bien ajouté les nouveaux tests ci-dessus dans le bon répertoire et la bonne classe.
\nNous allons maintenant ajouter la fonctionnalité Django décrite dans le ticket #24788.
\nPlacez-vous dans le dossier django/django/forms/ et ouvrez le fichier forms.py. Trouvez la classe BaseForm à la ligne 72 et ajoutez l’attribut de classe prefix juste après l’attribut field_order:
class BaseForm(object):\n # This is the main implementation of all the Form logic. Note that this\n # class is different than Form. See the comments by the Form class for\n # more information. Any improvements to the form API should be made to\n # *this* class, not to the Form class.\n field_order = None\n prefix = None\nAprès avoir terminé de modifier Django, nous devons être sûrs que les tests précédemment écrits réussissent, afin de vérifier que le code que nous venons d’écrire fonctionne correctement. Pour lancer les tests du dossier forms_tests, placez-vous dans le répertoire tests/ de Django et lancez :
$ ./runtests.py forms_tests\nOups, heureusement que nous avons écrit ces tests ! Vous devriez toujours voir un échec avec l’exception suivante :
\nAssertionError: None != 'foo'\nNous avons oublié d’ajouter l’instruction conditionnelle dans la méthode __init__. Poursuivez en modifiant la ligne self.prefix = prefix qui se trouve maintenant à la ligne 87 de django/forms/forms.py, en y ajoutant l’instruction conditionnelle :
if prefix is not None:\n self.prefix = prefix\nRelancez les tests et tout devrait réussir. Si ce n’est pas le cas, assurez-vous d’avoir bien modifié la classe BaseForm tel qu’indiqué ci-dessus et que vous avez copié le nouveau test correctement.
Après avoir vérifié que votre correctif et les tests fonctionnent correctement, il est recommandé de relancer toute la suite de tests de Django, simplement pour contrôler que vos modifications n’ont pas introduit des bogues dans d’autres parties de Django. Même si quand la suite de tests passe entièrement, ce n’est toujours pas une garantie que votre code ne contient pas d’erreurs, cela aide tout de même à révéler de nombreux bogues et régressions qui pourraient être passés inaperçus.
\nPour lancer la suite complète de tests de Django, placez-vous dans le répertoire tests/ de Django et lancez :
$ ./runtests.py\nTant que vous ne voyez pas apparaître d’erreurs, tout va pour le mieux.
\nCeci est une nouvelle fonctionnalité, elle doit donc être documentée. Ajoutez la section ci-après à la ligne 1068 (en fin de fichier) de django/docs/ref/forms/api.txt:
The prefix can also be specified on the form class::\n\n >>> class PersonForm(forms.Form):\n ... ...\n ... prefix = 'person'\n\n.. versionadded:: 1.9\n\n The ability to specify ``prefix`` on the form class was added.\nComme cette nouvelle fonctionnalité sera présente dans une version à venir, nous la mentionnons aussi dans les notes de publication de Django 1.9, à la ligne 164 en-dessous de la section « Formulaires » dans le fichier docs/releases/1.9.txt:
* A form prefix can be specified inside a form class, not only when\n instantiating a form. See :ref:`form-prefix` for details.\nPour plus d’informations sur l’écriture de documentation, y compris une explication sur la signification de versionadded, consultez Écrire la documentation. Cette page contient aussi une explication sur la manière de produire une copie locale de la documentation afin de pouvoir prévisualiser le code HTML qui sera généré.
Il est temps maintenant de passer en revue toutes les modifications effectuées dans notre correctif. Pour afficher les différences entre la copie actuelle de Django (incluant les modifications) et la révision que vous avez obtenue précédemment dans le tutoriel :
\n$ git diff\nUtilisez les touches fléchées pour avancer ou reculer.
\ndiff --git a/django/forms/forms.py b/django/forms/forms.py\nindex 509709f..d1370de 100644\n--- a/django/forms/forms.py\n+++ b/django/forms/forms.py\n@@ -75,6 +75,7 @@ class BaseForm(object):\n # information. Any improvements to the form API should be made to *this*\n # class, not to the Form class.\n field_order = None\n+ prefix = None\n\n def __init__(self, data=None, files=None, auto_id='id_%s', prefix=None,\n initial=None, error_class=ErrorList, label_suffix=None,\n@@ -83,7 +84,8 @@ class BaseForm(object):\n self.data = data or {}\n self.files = files or {}\n self.auto_id = auto_id\n- self.prefix = prefix\n+ if prefix is not None:\n+ self.prefix = prefix\n self.initial = initial or {}\n self.error_class = error_class\n # Translators: This is the default suffix added to form field labels\ndiff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt\nindex 3bc39cd..008170d 100644\n--- a/docs/ref/forms/api.txt\n+++ b/docs/ref/forms/api.txt\n@@ -1065,3 +1065,13 @@ You can put several Django forms inside one ``<form>`` tag. To give each\n >>> print(father.as_ul())\n <li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" /></li>\n <li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" /></li>\n+\n+The prefix can also be specified on the form class::\n+\n+ >>> class PersonForm(forms.Form):\n+ ... ...\n+ ... prefix = 'person'\n+\n+.. versionadded:: 1.9\n+\n+ The ability to specify ``prefix`` on the form class was added.\ndiff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt\nindex 5b58f79..f9bb9de 100644\n--- a/docs/releases/1.9.txt\n+++ b/docs/releases/1.9.txt\n@@ -161,6 +161,9 @@ Forms\n :attr:`~django.forms.Form.field_order` attribute, the ``field_order``\n constructor argument , or the :meth:`~django.forms.Form.order_fields` method.\n\n+* A form prefix can be specified inside a form class, not only when\n+ instantiating a form. See :ref:`form-prefix` for details.\n+\n Generic Views\n ^^^^^^^^^^^^^\n\ndiff --git a/tests/forms_tests/tests/test_forms.py b/tests/forms_tests/tests/test_forms.py\nindex 690f205..e07fae2 100644\n--- a/tests/forms_tests/tests/test_forms.py\n+++ b/tests/forms_tests/tests/test_forms.py\n@@ -1671,6 +1671,18 @@ class FormsTestCase(SimpleTestCase):\n self.assertEqual(p.cleaned_data['last_name'], 'Lennon')\n self.assertEqual(p.cleaned_data['birthday'], datetime.date(1940, 10, 9))\n\n+ def test_class_prefix(self):\n+ # Prefix can be also specified at the class level.\n+ class Person(Form):\n+ first_name = CharField()\n+ prefix = 'foo'\n+\n+ p = Person()\n+ self.assertEqual(p.prefix, 'foo')\n+\n+ p = Person(prefix='bar')\n+ self.assertEqual(p.prefix, 'bar')\n+\n def test_forms_with_null_boolean(self):\n # NullBooleanField is a bit of a special case because its presentation (widget)\n # is different than its data. This is handled transparently, though.\nLorsque la relecture du correctif est terminée, pressez sur la touche q pour revenir à la ligne de commande. Si le contenu du correctif est bon, il est temps de valider les modifications.
Pour valider les modifications :
\n$ git commit -a\nUn éditeur de texte apparaît pour rédiger le message de commit. Suivez les lignes directrices des messages de commit et écrivez un message comme :
\nFixed #24788 -- Allowed Forms to specify a prefix at the class level.\nAprès avoir validé le correctif (commit), envoyez-le vers votre fork GitHub (remplacez « ticket_24788 » par le nom de votre branche) :
\n$ git push origin ticket_24788\nVous pouvez créer une requête de contribution en visitant la page GitHub de Django. Vous verrez votre branche sous « Your recently pushed branches ». Cliquez sur « Compare & pull request » à côté du message.
\nNe le faites pas réellement pour ce tutoriel, mais sur la page suivante qui affiche l’aperçu du correctif, vous devriez cliquez sur « Create pull request ».
\nFélicitations, vous avez appris comment effectuer une requête de contribution pour Django ! Des détails sur des techniques plus avancées sont disponibles dans Travailler avec Git et GitHub.
\nVous pouvez mettre à profit maintenant ces compétences en aidant à améliorer la base de code de Django.
\nAvant de vous impliquer plus intensément dans l’écriture de correctifs pour Django, il est souhaitable de parcourir un peu plus d’informations destinées aux contributeurs :
\nIl est important de lire la documentation de Django sur l”appropriation de tickets et la soumission de correctifs. Cela comprend les règles de comportement sur Trac, la façon de vous assigner un ticket, le style attendu du code des correctifs et encore bien d’autres détails importants.
Les contributeurs débutants devraient aussi lire la documentation de Django pour les contributeurs débutants. Elle contient de nombreux bons conseils pour ceux d’entre nous qui débutent dans la contribution à Django.
Après cela, si vous êtes toujours avide de plus d’informations sur la contribution, vous pouvez toujours parcourir le reste de la documentation de Django sur la contribution. Elle contient plein d’informations utiles et devrait constituer votre source principale de réponses aux questions que vous vous posez.
Après avoir consulté une partie de ces informations, vous êtes fin prêt pour partir à la recherche d’un ticket pour lequel vous allez écrire un correctif. Commencez en priorité par les tickets marqués comme « Easy pickings » (résolution facile). Ces tickets sont souvent plus simples par nature et sont une cible idéale pour les contributeurs débutants. Lorsque vous serez à l’aise avec la contribution à Django, vous pourrez alors passer à la rédaction de correctifs pour des tickets plus difficiles.
\nSi vous voulez commencer tout de suite (et personne ne vous le reprochera), jetez un coup d’œil à la liste des tickets simples qui ont besoin d’un correctif et des tickets simples qui ont des correctifs nécessitant une amélioration. Si vous êtes à l’aise dans l’écriture de tests, vous pouvez aussi examiner la liste des tickets simples qui ont besoin de tests. N’oubliez pas de suivre les instructions sur l’attribution de tickets qui étaient mentionnées dans le lien sur la documentation de Django sur l”appropriation de tickets et la soumission de correctifs.
\nQuand un ticket possède un correctif, il doit être relu par une deuxième paire d’yeux. Après la soumission d’une requête de contribution, mettez à jour les métadonnées du ticket en définissant les drapeaux du ticket « has patch », « doesn’t need tests », etc, pour que d’autres puissent les retrouver en vue d’une relecture. Contribuer ne signifie pas nécessairement écrire un correctif à partir de zéro. La relecture de correctifs existants est également une contribution très utile. Consultez Tri des tickets pour plus de détails.
\n