La contribution sur drupal.org ne se fait pas via 'pull request' comme sur github mais fonctionne encore avec des patchs. Même si quelques modules sont disponibles sur github, ils ne sont censés être que des répliques, les repos principaux et les issues devant se gérer directement sur drupal.org.

Une documentation fixe la charte de bonne utilisation de git, ce qui permet d'aider les contributeurs à apprendre à générer un patch correct et permet au mainteneur de pointer vers cette documentation si besoin.

Le fait de fonctionner par patch joint à une issue permet au mainteneur de créer facilement un commit à partir du patch en question. Dans le cas où le correctif n'est pas encore commité, L'utilisation de patchs permet de corriger le module dans son projet tout en conservant l'information que ce module a été modifié et quelle est l'issue traitant de cette modification.

Si l'on devait prendre quelques bonne pratiques lors du traitement des issues et comprendre les différentes étapes de création d'un patch, ce serait les suivantes:

## Créer un patch

* Pour contribuer à un module (contrib ou core), commencer par récupérer le code de ce module via git, et non en téléchargeant le module.
* À partir de la branche de développement de votre version, ex: 8.x-1.x, créer la branche correspondant à votre issue. Le nommage est ici libre. Pour plus de praticité et puisqu'il est préférable de se fixer une convention pour s'y retrouver facilement, j'utilise [numero-issue]-[titre-issue]-[numero-commentaire], [titre-issue] étant le titre que fournit l'outil de suggestion de nom de patch. Cet outil limite le nombre de caractères et remplace les caractères spéciaux. Le [numero-commentaire] permet ensuite de faire la différence entre plusieurs patchs proposés. Nous verrons par la suite pourquoi j'ajoute le numéro de commentaires à la fin.

git checkout -b [numero-issue]-[titre-issue]-[numero-commentaire]

* Maintenant que la branche est créée, je peux apporter mes modifications (en les vérifiant) et les commiter. Concernant le nom du commit, je reprend le format proposé en bas de l'issue, à savoir "Issue #[numero-issue] by [user list of people contributing on issue]: [issue title]".
* Je peux désormais générer mon commit. Je me met à jour avec le repository distant (remote) dans un premier temps, puis j'utilise alors la commande suggérée par la documentation pour générer le patch en y ajoutant les informations de contributeur et en prenant pour nom le nom donné par l'outil de suggestion de drupal:
git fetch origin/8.x-1.x
git format-patch origin/8.x-1.x --stdout > [titre-issue]-[numero-issue]-[numero-commentaire].patch
À noter que le numéro de commentaire est le numéro du futur commentaire que je vais créer pour ajouter ce patch, et non une référence à un quelconque commentaire existant.

* Je relis le patch une dernière fois pour vérifier que celui-ci correspond bien à mes modifications avant de soumettre le commentaire.
* En soumettant le commentaire, je passe le statut en "needs review". Cela permet de notifier au mainteneur et aux contributeurs qu'un patch a été utilisé. Il peuvent ainsi lire et tester le patch. Dans le cas ou le module en question intègre des tests automatiques, ces tests seront également déclenchés.

## Générer un patch avec son fichier diff suite à des demandes de modification

* Dans le cas où mon patch est jugé insuffisant (échec des tests automatique, ne respecte pas les bonnes pratiques de coding [coding standards](https://www.drupal.org/coding-standards), est susceptible d'apporter de nouveaux bugs, ne fonctionne pas comme souhaité etc), le statut de l'issue sera de passé en "needs work" et il faudra alors fournir un nouveau patch en prenant en compte les remarques.
* Dans le cas où le patch est jugé correct (en général on attend qu'il soit validé par 2 personnes à minima suivant la popularité de l'issue), un contributeur autre que l'auteur du patch passe le statut en "RTBC" (Reviewed & Tested By the Community), ce qui indique alors au mainteneur que le patch a été jugé correct par la communauté et qu'il peut (et non doit) le commiter. Jusqu'à ce qu'il soit commité, le mainteneur ou tout autre contributeur peut à tout moment repasser cette issue en statut "needs work" en justifiant la raison.
* Dans les cas où des modifications sur le patch sont demandées, il faudra alors uploader en plus du patch un fichier "diff" montrant les différences entre le précédent patch et le nouveau patch. Cela permet aux contributeur de voir en un coup d'oeil les modifications apportées, les correctifs comme les erreurs.
* Le patch ne doit contenir qu'un seul commit pour faciliter sa lecture, ce qui nous amène à la raison de nommer mes branches avec le numéro de commentaire. À partir de la branche contenant les modifications du dernier commentaire (si vous n'êtes pas l'auteur du dernier commentaire, suivez l'étape de création de patch, les modifications seront celles appliquées par le dernier patch), je créé une nouvelle branche en précisant le numéro du nouveau commentaire.
* J'apporte les correctifs demandés.
* J'ajoute mes fichiers en vérifiant mes modifications puis commit en modifiant le précédent commit.

git commit --amend

* Je génère mon patch comme précédemment et vérifie que le fichier est correct.
* Je peux désormais faire un différenciel entre mes deux branches qui représentent les 2 patchs. L'avantage de fonctionner par branche plutôt que par commits directement est que je pourrais à tout moment revenir sur un précédent patch si besoin.

git diff [numero-issue]-[titre-issue]-[numero-commentaire-precedent] [numero-issue]-[titre-issue]-[numero-commentaire] > interdiff-[numero-issue]-[numero-commentaire-precedent]-[numero-commentaire].txt

* Je vérifie le fichier diff et peux ensuite le soumettre en même temps que mon patch.

## Outils d'aide à la contribution de drupal.org

* Précédemment, il fallait renseigner correctement ses informations de compte git et les inclure dans son patch (via format-patch) pour faciliter le crédit des commits. Désormais, une interface sur chaque issue simplifie le fonctionnement et il est possible de sélectionner les contributeurs que l'on souhaite créditer, ce qui génère le commit avec les paramètres précis à saisir.
* La dernière nouveauté est la possibilité à chaque contributeur de préciser dans quel cadre il a contribué, et donc de promouvoir la société qui l'emploie ainsi que le commanditaire du projet si le correctif a eu lieu dans le cadre d'un projet client (et donc financé par le client).
* Plusieurs boutons permettent de simplifier la rédaction des issues. On dispose entre autres:
* D'un bouton pour générer des templates de création d'issue.
* D'un bouton pour ajouter des taches à cette issue.
* D'un bouton pour générer le nom du prochain patch
* Il est possible depuis longtemps d'intégrer des tests automatiques à ses projets. Ce sytème a évolué en passant de [Legacy PIFR/PIFT Testbots](https://www.drupal.org/project/testbot) à [drupalCI](https://www.drupal.org/project/drupalci) mais le principe est identique. Ce système permet de vérifier automatiquement que le patch soumis valide les tests et donc n'apporte pas de régression. [Plus d'informations sur les tests automatiques de Drupal.org](https://www.drupal.org/automated-testing).
* Côté outils pratiques, l'outil [Dreditor](https://dreditor.org/) est un must have. Cette extension à ajouter à son navigateur permet de visualiser un patch de manière plus lisible et de commenter directement des portions de code. Il permet de faire facilement de la re-lecture de code et d'annoter les modifications à apporter.

## Récapitulatif:

* Le patch doit respecter les [coding standards de Drupal](https://www.drupal.org/coding-standards).
* Le patch ne doit contenir qu'un seul commit.
* Fournir un [diff](https://www.drupal.org/documentation/git/interdiff) si l'issue dispose de plusieurs patchs et que l'on apporte des modifications à l'un d'eux.

# Liens utiles

* [Documentation contribution et bonnes pratiques Drupal](https://www.drupal.org/developing/best-practices)
* [Documentation contribution git](https://www.drupal.org/node/1137316)
* [Documentation contribution pour générer un patch](https://www.drupal.org/node/707484)
* [Documentation drupal pour générer diff](https://www.drupal.org/documentation/git/interdiff)