Mathieu Agopian : Contribuer à Django, premiers pas (patcher la doc)

Modifier la documentation

Pour cela, il faut déjà repérer la page concernée dans la documentation de Django. Toujours en nous référant au ticket #15886 de l'exemple, un gentil contributeur a déjà apporté un commentaire, et indiqué le lien vers la page http://docs.djangoproject.com/en/1.3/topics/serialization/ (oui, ça tombe bien, ce gentil contributeur, c'était moi ;)).

Si on inspecte l'url, on peut voir qu'il s'agit de la page "serialization" dans la catégorie "topics". Le fichier correspondant, dans le code source de Django, se trouve donc logiquement dans

$ cd ~/projects/django/docs
$ vi serialization.txt

Dans mon cas, j'utilise le meilleur des éditeur, mais vous avez bien entendu le choix des armes ;)

Une fois le bon endroit localisé pour apporter la clarification demandée dans le ticket, il suffit de rajouter quelques lignes, en utilisant son meilleur anglais.

Il est à ce propos fortement conseillé d'avoir au moins quelques notions de sphinx, l'outil utilisé pour générer la doc, et connaître les ajouts apportés pour Django dans la page sur la contribution à la documentation.

Compiler la documentation

Nous l'avons vu dans le précédent article, il suffit pour celà d'utiliser la commande suivante :

$ make html

Si il y a le moindre problème de syntaxe reStructuredText vous le verrez lors de l'exécution de cette commande. Il suffit alors de consulter le résultat sur file:///chemin/vers/projects/django/docs/_build/html/index.html.

Créer le patch

Si vous avez suivi la méthode proposé dans le précédent article, vous avez le cloné le miroir git de Django, et pouvez donc utilisez la méthode ultra simple suivante :

1. créer une branche de développement pour y stocker les modifications à apporter : $ git checkout -b dev
2. apporter les modifications nécessaires
3. commit les changements régulièrement, et retourner en 2. tant que c'est nécessaire : $ git commit -a -m "un message de commit"
4. une fois fini, créer le patch : $ git diff master > nom_de_mon_patch.diff

Il est très fortement recommandé de créer un patch avec l'extension .diff pour qu'il soit correctement traité et affiché par trac, et de l'attacher au ticket (au lieu de pointer vers un diff ou un pull request sur github ou autre), pour simplifier au maximum la dure et (déjà) fastidieuse tâche des core developpers.

Et surtout ne pas oublier de rajouter le flag "has patch" !

Pour reprendre notre exemple, vous pouvez visualiser le patch final.

Attendre la validation de la communauté

Dans ce cas précis, j'étais inquiet de la dépendance qu'il pouvait y avoir sur le ticket #15889, qui est le ticket créé en parallèle pour la demande d'ajout de fonctionnalité (renvoyer une exception spécifique au lieu de KeyError). En effet, si le ticket #15889 était intégré dans Django (avec la documentation associée), avant le ticket #15886, il résulterait un problème de cohérence, avec deux parties de la même documentation indiquant une levée d'exception différente.

J'ai donc soulevé la question sur le salon irc #django-dev, et la réaction a été rapide : Alex a eu la gentillesse de répondre à mes craintes en fermant le ticket comme étant un duplicat du ticket #15889.

Bah oui, mais mon patch alors ?

Et là, j'ai envie de répondre : "C'est le jeu, ma pov' Lucette" !

Plus sérieusement, peu importe le temps passé (dans ce cas, vraiment minime) sur un ticket, au final le but est de

• rendre Django meilleur
• apporter sa modeste contribution si nécessaire
• faciliter au maximum la tâche des core devs
• apprendre le plus possible au passage quand l'opportunité se présente