Cet article est le second d’une série dédiée à la contribution au cœur WordPress. Aujourd’hui, l’objectif est d’expliquer comment créer un patch pour proposer un correctif ou une amélioration dans le cœur WordPress.
Voir l’article précédent : comprendre le fonctionnement de Trac, l’outil de ticket de WordPress.
If you think of the ideas of open source applied to information in an encyclopedia, you get to Wikipedia – lots and lots of small contributions that bubble up to something that’s meaningful.
Matt Mullenweg
Sommaire de l’article :
- Workflow : comment se matérialise un patch
- Travailler sur le cœur WordPress avec GIT : la méthode basique
- Création d’un patch pas à pas
- Quelques ressources pour aller plus loin
Workflow : comment se matérialise un patch
Un patch est un bout de code censé apporter une correction ou une amélioration au cœur WordPress. Ce patch se matérialise par un fichier texte contenant l’ensemble du différentiel sur les fichiers du cœur entre avant et après votre intervention.
Bien entendu, ce fichier ne contient pas tout WordPress : il contient uniquement les index des lignes ajoutées/supprimées/modifiées et le fichier peut être appliqué via un outil de versionnement tel que GIT ou SVN pour constater le résultat de la modification.
Ces fichiers de différentiel sont nommés d’après le numéro du ticket associé sur Trac – voir l’article précédent de la série – et possèdent l’extension .patch ou plus fréquemment .diff. Un fichier de différentiel portant sur le ticket 44904 se nommera donc 44904.diff.
Si le correctif n’est pas complet et qu’un nouveau fichier différentiel est créé pour améliorer la première version, on le nommera 44904.2.diff et ainsi de suite pour les suivants.
Ci-dessous, une capture d’un fichier de différentiel tel qu’on peut le visualiser sur le Trac WordPress.org. En rouge, le code supprimé du fichier nav-menu.php et en vert le code qui a été ajouté à la place.
Travailler sur le cœur WordPress avec GIT : la méthode basique
Dans cet article, nous allons en premier lieu voir une façon de procéder assez «basique», avant d’aller plus loin dans un prochain article. En effet, WordPress a récemment mis en place un nouveau process de «build» du cœur WP, et dans un premier temps nous allons simplement nous concentrer sur la génération d’un fichier de différentiel et son envoi sur Trac.
Récupérer WordPress depuis le dépôt miroir GitHub officiel
Historiquement, le projet WordPress est versionné sur un dépôt SVN. Devant la montée en puissance de l’outil de versionnement GIT, des solutions ont été mises en place afin de permettre aux utilisateurs et utilisatrices de GIT de pouvoir facilement travailler avec leurs outils habituels.
Un dépôt a donc été mis en place sur GitHub
> https://github.com/WordPress/wordpress-develop
Ce dépôt est automatiquement synchronisé avec le dépôt SVN du projet. Il vous permet donc de récupérer la dernière version de travail (trunk) du projet.
Pour ce faire, créez un dossier sur votre ordinateur, ouvrez votre console, positionnez-vous sur ce dossier et clonez le dépôt GitHub avec la commande suivante :
git clone https://github.com/WordPress/wordpress-develop.gitEnsuite, positionnez-vous sur le répertoire cloné :
cd wordpress-developEnsuite nous allons dupliquer la branche trunk (ce que nous avons récupéré) afin de créer une branche dédiée à notre patch. Je nomme ma branche avec le numéro du ticket plus quelques mots de description permettant de le retrouver plus tard plus facilement.
git branch 42740-relative-link-image-widgetEnsuite je me positionne dans cette nouvelle branche car c’est ici que je ferais mes modifications sur le cœur WordPress.
git checkout 42740-relative-link-image-widgetNote : l’arborescence des fichiers du dépôt wordpress-develop
L’arborescence de la version de développement de WordPress diffère un peu de celle d’un WordPress classique. Tout ce qu’il y a à savoir pour l’instant, c’est que vos fichiers WP classiques se trouvent dans le répertoire /src.
Cet arborescence est différente car elle contient un mécanisme permettant de «build» une installation WordPress en ligne de commande et de lancer des tests unitaires automatiques permettant de vérifier que le nouveau code que vous avez introduit n’entraîne pas de régression sur WP. Mais tout cela est destiné à un usage avancé que nous n’aborderons pas aujourd’hui 🙂
Création d’un patch pas à pas
Pour ce tutoriel, nous allons imaginer que nous travaillons sur le ticket #42740 – qui a déjà été corrigé et intégré au cœur WordPress, voici un lien pour consulter le ticket complet.
Pour décrire la correction en question, il s’agissait d’autoriser d’utiliser des liens relatifs dans le champ URL du Widget Image de WordPress, par exemple pour créer une ancre. En effet, le champ n’autorisait précédemment pas d’accueillir une valeur comme #mon_ancre.
Réaliser et tester un patch
Dans ce premier article, nous allons simplifier la procédure. Tout d’abord, j’installe WordPress (de façon classique) en local.
J’identifie ensuite le ou les fichiers à corriger sur le cœur WP (les méthodes permettant de le faire pourront faire l’objet d’un article dédié si besoin).
Ici, s’agissant du Widget Image, il s’agit du fichier class-wp-widget-media-image.php situé dans le répertoire /wp-includes/widgets/ . Il faut remplacer l’ancien code :
<input id="{{ elementIdPrefix }}linkUrl" type="url" class="widefat link" value="{{ data.link_url }}" placeholder="http://">…afin d’autoriser un champ de type url à accepter un texte ne commençant pas par http:// ou https://. On utilise pour cela une expression régulière ajoutée dans un attribut pattern :
<input id="{{ elementIdPrefix }}linkUrl" type="text" class="widefat link" value="{{ data.link_url }}" placeholder="http://" pattern="((\w+:)?\/\/\w.*|\w+:(?!\/\/$)|\/|\?|#).*">Je teste donc le rendu dans mon Administration WordPress pour vérifier que le patch s’applique :
Effectivement, le correctif semble fonctionnel. J’en profite pour prendre une capture d’écran du résultat pour ajouter cette capture dans le ticket et montrer le résultat obtenu.
Création du fichier .diff hébergeant le patch
Je retourne dans le dossier de mon clone du dépôt GIT, je vais dans le dossier /src et je reproduis manuellement ma modification du fichier.
Ensuite, nous allons générer un fichier de différentiel entre la branche du patch 42740-relative-link-image-widget et la branche trunk :
git diff trunk > 42740.diffOn obtient un fichier créé automatiquement dans votre dossier wordpress-develop et ressemblant à cela :
diff --git a/src/wp-includes/widgets/class-wp-widget-media-image.php b/src/wp-includes/widgets/class-wp-widget-media-image.php
index e374b57..8a95135 100644
--- a/src/wp-includes/widgets/class-wp-widget-media-image.php
+++ b/src/wp-includes/widgets/class-wp-widget-media-image.php
@@ -329,7 +329,7 @@ class WP_Widget_Media_Image extends WP_Widget_Media {
<# if ( data.url ) { #>
<p class="media-widget-image-link">
<label for="{{ elementIdPrefix }}linkUrl"><?php esc_html_e( 'Link to:' ); ?></label>
- <input id="{{ elementIdPrefix }}linkUrl" type="url" class="widefat link" value="{{ data.link_url }}" placeholder="http://">
+ <input id="{{ elementIdPrefix }}linkUrl" type="text" class="widefat link" value="{{ data.link_url }}" placeholder="http://" pattern="((\w+:)?\/\/\w.*|\w+:(?!\/\/$)|\/|\?|#).*">
</p>
<# } #>
</script>Poster son patch sur Trac
Une fois le fichier .diff créé, il faut se rendre sur le ticket correspondant, dans les attachments et ajouter le fichier de différentiel en pièce jointe.
Il est recommandé d’ajouter une ou plusieurs captures d’écran avant/après (mais cela dépend du ticket).
Ensuite, il faut publier un commentaire sur le ticket en indiquant les modifications faites et en quoi elles sont à même de résoudre le problème rencontré.
Lors de la publication du commentaire, pensez à ajouter le keyword «has-patch» pour que le ticket remonte dans les tickets ayant actuellement un correctif.
Suite (et fin ?)
Ensuite, un « component maintainer » (cf article précédent) viendra vérifier votre patch, le tester et l’approuver. Ce travail peut aussi souvent être réalisé par un responsable de la prochaine version mineure du CMS si le patch n’a pas un périmètre de modification trop important sur le cœur et que les responsables de la version correspondante ont choisi de l’inclure dans leur version.
Il est possible (et fort probable lors de vos premiers patches) que l’on vous demande de modifier tel ou tel élément de votre fichier .diff pour aboutir à un meilleur résultat. Dans ce cas il « suffit » de reprendre votre branche GIT et de reproduire le travail effectué auparavant 🙂
Quelques ressources pour aller plus loin
- Le Core Contributor Handbook (en anglais) est la ressource principale pour participer au développement du cœur WordPress
- Aller plus loin sur l’usage du cœur WP avec GIT (en anglais)
- Installer le cœur WordPress en local (en anglais)
- L’organisation du code dans WordPress (en anglais), mais ça, nous allons en reparler très bientôt 🙂
- Créer un patch avec SVN sur le cœur WordPress (en anglais), ce qui est l’équivalent de ce tutoriel pour celles et ceux qui utilisent SVN au lieu de GIT
- Les bonnes pratiques pour réaliser de bons patches (en anglais), facilement testables et donc rapidement pris en compte par l’équipe cœur WordPress.
Laisser un commentaire
Vous devez vous connecter pour publier un commentaire.