Writing your first contribution for Django¶
Introduction¶
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.
La 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, le chemin est tout tracé avec de la documentation, des outils ainsi qu’une communauté pour vous épauler. Nous allons vous accompagner tout au long de ce processus afin que vous puissiez apprendre par un exemple.
À qui est destiné ce tutoriel ?¶
Voir aussi
Si vous cherchez une référence sur la façon de contribuer au code de Django, consultez la documentation Écriture du code.
Pour 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.
Ceux 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.
Mais pour la plus grande partie, ce tutoriel vise à expliquer le plus possible de choses pour qu’il puisse convenir au plus grand nombre.
Où obtenir de l’aide :
Si vous avez des problèmes en suivant ce tutoriel, vous pouvez écrire (en anglais) sur le forum Django, à la liste django-developers ou utiliser le canal IRC #django-dev sur irc.libera.chat (ou #django-fr en français) pour discuter avec d’autres utilisateurs Django qui pourront peut-être vous aider.
Quels sont les contenus de ce tutoriel ?¶
We’ll be walking you through contributing to Django for the first time. By the end of this tutorial, you should have a basic understanding of both the tools and the processes involved. Specifically, we’ll be covering the following:
- installation de Git,
- Téléchargement d’une copie de la version de développement de Django.
- le lancement de la suite de tests de Django,
- Writing a test for your changes.
- Writing the code for your changes.
- Testing your changes.
- 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.
Python 3 indispensable !
La version actuelle de Django ne prend plus en charge Python 2.7. Obtenez Python 3 depuis la page des téléchargements de Python ou par l’intermédiaire du gestionnaire des paquets de votre système.
Pour les utilisateurs Windows
Consultez Installation de Python dans la documentation à propos de Windows pour de plus amples indications.
Code de conduite¶
En tant que contributeur, vous pouvez nous aider à maintenir la communauté Django ouverte et accueillante. Lisez et respectez notre Code de conduite.
Installation de Git¶
For this tutorial, you’ll need Git installed to download the current development version of Django and to generate a branch for the changes you make.
Pour 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.
Téléchargement d’une copie de la version de développement de Django¶
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 :
$ git clone https://github.com/YourGitHubName/django.git
...\> git clone https://github.com/YourGitHubName/django.git
Connexion à faible bande passante ?
Vous pouvez ajouter l’option --depth 1 à git clone pour éviter le téléchargement de l’historique complet de Django, ce qui réduit le transfert de données de ~250 Mo à ~70 Mo.
Maintenant 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, 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 un nouvel environnement virtuel en exécutant :
$ python3 -m venv ~/.virtualenvs/djangodev
...\> py -m venv %HOMEPATH%\.virtualenvs\djangodev
Le chemin correspond à l’endroit où le nouvel environnement sera enregistré sur votre ordinateur.
La dernière étape de configuration de l’environnement virtuel est de l’activer :
$ source ~/.virtualenvs/djangodev/bin/activate
Si la commande source n’est pas disponible, vous pouvez essayer d’utiliser un point à la place :
$ . ~/.virtualenvs/djangodev/bin/activate
Vous devez activer l’environnement virtuel chaque fois que vous ouvrez une nouvelle fenêtre de terminal.
Pour les utilisateurs Windows
Pour activer votre environnement virtuel sur Windows, lancez :
...\> %HOMEPATH%\.virtualenvs\djangodev\Scripts\activate.bat
Le nom de l’environnement virtuel actuellement actif est affiché sur la ligne de commande pour vous aider à voir d’un coup d’œil lequel est activé. Tout ce que vous installez avec pip quand ce nom est affiché sera installé dans cet environnement virtuel, isolé des autres environnements et des paquets du système.
Poursuivez en installant la copie de Django précédemment chargée :
$ python -m pip install -e /path/to/your/local/clone/django/
...\> py -m pip install -e \path\to\your\local\clone\django\
The installed version of Django is now pointing at your local copy by installing in editable mode. You will immediately see any changes you make to it, which is of great help when writing your first contribution.
Création de projets avec une copie locale de Django¶
It may be helpful to test your local changes with a Django project. First you have to create a new virtual environment, install the previously cloned local copy of Django in editable mode, and create a new Django project outside of your local copy of Django. You will immediately see any changes you make to Django in your new project, which is of great help when writing your first contribution, especially if testing any changes to the UI.
Vous pouvez suivre le tutoriel pour obtenir de l’aide à la création d’un projet Django.
Lancement de la suite de test de Django pour la première fois¶
En 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 vos modifications fonctionnent et n’ont pas cassé d’autres parties de Django. Si vous n’avez encore jamais lancé la suite de tests de Django, il est recommandé de le faire une fois au préalable pour vous familiariser avec le résultat obtenu.
Avant de lancer la suite de tests, entrez dans le répertoire tests/ de Django avec la commande cd tests et installez les dépendances de test en exécutant :
$ python -m pip install -r requirements/py3.txt
...\> py -m pip install -r requirements\py3.txt
Si 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.
Nous sommes maintenant prêts à lancer la suite de tests. Si vous utilisez GNU/Linux, macOS ou une autre version de Unix, lancez :
$ ./runtests.py
...\> runtests.py
Maintenant prenez place et détendez-vous. La suite complète de tests Django contient des milliers de tests, ce qui prend plusieurs minutes au moins à s’exécuter, en fonction de la rapidité de votre ordinateur.
Pendant 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 Lancement de tous les 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 Utilisation d’un autre module de réglages settings.
Lorsque 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 Lancement des tests unitaires pour plus d’informations.
Il faut savoir que la version main (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.
Note
Pour ce tutoriel et le ticket sur lequel nous travaillons, il est suffisant de tester avec SQLite. Cependant, il est possible (et parfois nécessaire) de lancer les tests en utilisant une base de données différente. Lorsque vous apportez des modifications à l’interface utilisateur, vous aurez besoin de lancer les tests Selenium.
Travail sur une fonctionnalité¶
Pour ce tutoriel, nous allons travailler sur un ticket factice comme cas d’étude. Voici les détails imaginaires :
Ticket #99999 – Permettre de faire des toasts
Django devrait fournir une fonction django.shortcuts.make_toast() qui renvoie 'toast'.
Nous allons maintenant implémenter cette fonctionnalité et les tests qui l’accompagnent.
Creating a branch¶
Avant toute modification, créez une nouvelle branche pour le ticket :
$ git checkout -b ticket_99999
...\> git checkout -b ticket_99999
Vous êtes libre de choisir le nom de la branche, « ticket_99999 » 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.
Écriture de quelques tests pour le ticket¶
In most cases, for a contribution to be accepted into Django it has to include tests. For bug fix contributions, this means writing a regression test to ensure that the bug is never reintroduced into Django later on. A regression test should be written in such a way that it will fail while the bug still exists and pass once the bug has been fixed. For contributions containing new features, you’ll need to include tests which ensure that the new features are working correctly. They too should fail when the new feature is not present, and then pass once it has been implemented.
A good way to do this is to write your new tests first, before making any changes to the code. This style of development is called test-driven development and can be applied to both entire projects and single changes. After writing your tests, you then run them to make sure that they do indeed fail (since you haven’t fixed that bug or added that feature yet). If your new tests don’t fail, you’ll need to fix them so that they do. After all, a regression test that passes regardless of whether a bug is present is not very helpful at preventing that bug from reoccurring down the road.
Entrons maintenant dans le vif du sujet.
Écriture d’un test pour le ticket #99999¶
Afin de résoudre ce ticket, nous allons ajouter une fonction make_toast() au module django.shortcuts. Pour commencer, nous écrirons un test qui essaie d’utiliser cette fonction et qui vérifie que son résultat est correct.
Placez-vous dans le dossier tests/shortcuts/ et créez un nouveau fichier test_make_toast.py. Ajoutez le code suivant
from django.shortcuts import make_toast
from django.test import SimpleTestCase
class MakeToastTests(SimpleTestCase):
def test_make_toast(self):
self.assertEqual(make_toast(), "toast")
Ce test vérifie que la fonction make_toast() renvoie 'toast'.
Mais cette histoire de tests semble plutôt compliquée…
Si vous n’avez jamais eu affaire à des tests précédemment, ils peuvent paraître un peu difficiles à écrire au premier abord. Heureusement, les tests sont un sujet très important en programmation, il existe donc beaucoup d’informations à leur sujet :
- Une première approche conseillée dans l’écriture de tests pour Django est de parcourir la documentation Écriture et lancement de tests.
- Dive Into Python (un livre en ligne gratuit pour les développeurs débutants en Python) contient une très bonne section sur l”introduction aux tests unitaires.
- Après ces lectures, si vous désirez un peu plus de matière à digérer, vous pouvez toujours parcourir la documentation Python de
unittest.
Lancement des nouveaux tests¶
Comme nous n’avons encore effectué aucune modification à django.shortcuts, notre test est censé échouer. Lançons tous les tests dans le dossier shortcuts pour être certain que c’est vraiment ce qui va se passer. Placez-vous dans le répertoire tests/ de Django et lancez :
$ ./runtests.py shortcuts
...\> runtests.py shortcuts
Si les tests se sont déroulés correctement, vous devriez voir un échec correspondant à la méthode de test que nous avons ajoutée, avec cette erreur :
ImportError: cannot import name 'make_toast' from 'django.shortcuts'
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 le bon nom de fichier.
Écriture du code pour le ticket¶
Ensuite, nous allons ajouter la fonction make_toast().
Passez dans le dossier django/ et ouvrez le fichier shortcuts.py. Au bas du fichier, ajoutez
def make_toast():
return "toast"
Nous devons maintenant être sûrs que le test précédemment écrit réussit, afin de vérifier que le code que nous venons d’ajouter fonctionne correctement. Placez-vous une nouvelle fois dans le répertoire tests/ de Django et lancez :
$ ./runtests.py shortcuts
...\> runtests.py shortcuts
Tous les tests devraient réussir. Si ce n’est pas le cas, assurez-vous d’avoir ajouté la bonne fonction dans le bon fichier.
Lancement de la suite de tests de Django pour la seconde fois¶
Once you’ve verified that your changes and test are working correctly, it’s a good idea to run the entire Django test suite to verify that your change hasn’t introduced any bugs into other areas of Django. While successfully passing the entire test suite doesn’t guarantee your code is bug free, it does help identify many bugs and regressions that might otherwise go unnoticed.
Pour lancer la suite complète de tests de Django, placez-vous dans le répertoire tests/ de Django et lancez :
$ ./runtests.py
...\> runtests.py
Écriture de la documentation¶
Ceci est une nouvelle fonctionnalité, elle doit donc être documentée. Ouvrez le fichier docs/topics/http/shortcuts.txt et ajoutez le contenu ci-après à la fin du fichier :
``make_toast()``
================
.. function:: make_toast()
.. versionadded:: 2.2
Returns ``'toast'``.
Comme cette nouvelle fonctionnalité sera présente dans une version à venir, nous la mentionnons aussi dans les notes de publication de la prochaine version de Django. Ouvrez les notes de publication de la version la plus récente dans docs/releases/ (2.2.txt au moment de cette rédaction). Ajoutez une note sous le chapitre « Minor Features »:
:mod:`django.shortcuts`
~~~~~~~~~~~~~~~~~~~~~~~
* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
Pour 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é.
Aperçu des changements¶
Now it’s time to review the changes made in the branch. To stage all the changes ready for commit, run:
$ git add --all
...\> git add --all
Puis affichez les différences entre votre copie actuelle de Django (incluant vos modifications) et la révision que vous avez initialement extraite précédemment dans ce tutoriel avec :
$ git diff --cached
...\> git diff --cached
Utilisez les touches fléchées pour avancer ou reculer.
diff --git a/django/shortcuts.py b/django/shortcuts.py
index 7ab1df0e9d..8dde9e28d9 100644
--- a/django/shortcuts.py
+++ b/django/shortcuts.py
@@ -156,3 +156,7 @@ def resolve_url(to, *args, **kwargs):
# Finally, fall back and assume it's a URL
return to
+
+
+def make_toast():
+ return 'toast'
diff --git a/docs/releases/2.2.txt b/docs/releases/2.2.txt
index 7d85d30c4a..81518187b3 100644
--- a/docs/releases/2.2.txt
+++ b/docs/releases/2.2.txt
@@ -40,6 +40,11 @@ database constraints. Constraints are added to models using the
Minor features
--------------
+:mod:`django.shortcuts`
+~~~~~~~~~~~~~~~~~~~~~~~
+
+* The new :func:`django.shortcuts.make_toast` function returns ``'toast'``.
+
:mod:`django.contrib.admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/topics/http/shortcuts.txt b/docs/topics/http/shortcuts.txt
index 7b3a3a2c00..711bf6bb6d 100644
--- a/docs/topics/http/shortcuts.txt
+++ b/docs/topics/http/shortcuts.txt
@@ -271,3 +271,12 @@ This example is equivalent to::
my_objects = list(MyModel.objects.filter(published=True))
if not my_objects:
raise Http404("No MyModel matches the given query.")
+
+``make_toast()``
+================
+
+.. function:: make_toast()
+
+.. versionadded:: 2.2
+
+Returns ``'toast'``.
diff --git a/tests/shortcuts/test_make_toast.py b/tests/shortcuts/test_make_toast.py
new file mode 100644
index 0000000000..6f4c627b6e
--- /dev/null
+++ b/tests/shortcuts/test_make_toast.py
@@ -0,0 +1,7 @@
+from django.shortcuts import make_toast
+from django.test import SimpleTestCase
+
+
+class MakeToastTests(SimpleTestCase):
+ def test_make_toast(self):
+ self.assertEqual(make_toast(), 'toast')
When you’re done previewing the changes, hit the q key to return to the
command line. If the diff looked okay, it’s time to commit the changes.
Committing the changes¶
Pour valider les modifications :
$ git commit
...\> git commit
Un é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 :
Fixed #99999 -- Added a shortcut function to make toast.
Envoi du commit et création de la requête de contribution¶
After committing the changes, send it to your fork on GitHub (substitute « ticket_99999 » with the name of your branch if it’s different):
$ git push origin ticket_99999
...\> git push origin ticket_99999
Vous 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.
Please don’t do it for this tutorial, but on the next page that displays a preview of the changes, you would click « Create pull request ».
Étapes suivantes¶
Fé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.
Vous pouvez mettre à profit maintenant ces compétences en aidant à améliorer la base de code de Django.
Plus d’informations pour les nouveaux contributeurs¶
Before you get too into contributing to Django, there’s a little more information on contributing that you should probably take a look at:
- You should make sure to read Django’s documentation on claiming tickets and submitting pull requests. It covers Trac etiquette, how to claim tickets for yourself, expected coding style (both for code and docs), and many other important details.
- 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.
Recherche de votre premier vrai ticket¶
Once you’ve looked through some of that information, you’ll be ready to go out and find a ticket of your own to contribute to. Pay special attention to tickets with the « easy pickings » criterion. These tickets are often much simpler in nature and are great for first time contributors. Once you’re familiar with contributing to Django, you can start working on more difficult and complicated tickets.
If you just want to get started already (and nobody would blame you!), try taking a look at the list of easy tickets without a branch and the easy tickets that have branches which need improvement. If you’re familiar with writing tests, you can also look at the list of easy tickets that need tests. Remember to follow the guidelines about claiming tickets that were mentioned in the link to Django’s documentation on claiming tickets and submitting branches.
Que se passe-t-il après la création d’une requête de contribution ?¶
After a ticket has a branch, it needs to be reviewed by a second set of eyes. After submitting a pull request, update the ticket metadata by setting the flags on the ticket to say « has patch », « doesn’t need tests », etc, so others can find it for review. Contributing doesn’t necessarily always mean writing code from scratch. Reviewing open pull requests is also a very helpful contribution. See Tri des tickets for details.
