Pull requests

Les Pull Requests (PR) sont l'outil intégré de Tuleap pour la revue de code. Elles permettent à un développeur de proposer des modifications sur une branche, à l'équipe de les examiner ligne par ligne, puis à un intégrateur de valider et fusionner le code dans la branche principale.

Information
Tuleap supporte également la revue de code avec Gerrit pour les organisations qui préfèrent un workflow de revue par patch.

Pré-requis

Le plugin "Pull Request" doit être installé et activé dans le projet.
Le service Git doit être actif avec au moins un dépôt.

Liste des Pull requests

La page d'accueil des Pull Requests du dépôt affiche la liste de toutes les PR.

Une barre de filtres permet de naviguer efficacement dans les résultats :

Par état : ouvertes ou fermées (fusionnées et abandonnées).
Par auteur, par relecteur, par labels, par branche (source ou destination).
Par mots-clés : recherche dans le titre et la description.
"En lien avec moi" : n'affiche que les PR où vous êtes auteur ou relecteur.

Le tri par date de création (ascendant ou descendant) et la pagination complètent les options de navigation.

Créer une Pull Request

Pour proposer des modifications, poussez votre branche de développement sur le dépôt Tuleap, puis cliquez sur "Créer une pull request" depuis la page du dépôt. Sélectionnez la branche source (vos modifications) et la branche destination (par exemple main).

Le titre est automatiquement extrait du premier message de commit. La description reprend le reste de ce message. Ces deux champs sont modifiables à tout moment via le bouton "Éditer le titre" ou en cliquant directement sur la description dans l'onglet Résumé. La description supporte la syntaxe Markdown (CommonMark) et dispose d'un mode "Aperçu" pour visualiser le rendu avant validation.

Vous pouvez également créer une PR depuis un fork personnel : sélectionnez votre fork comme source et le dépôt de référence comme destination. Tuleap gère nativement les PR entre dépôts (cross-repository), ce qui permet à un contributeur de proposer des modifications depuis son fork vers le dépôt principal du projet.

Créer une PR depuis un artifact

Depuis un Artifact de vos Trackers, vous pouvez créer directement une branche Git et la PR associée via les actions de l'Artifact. Consultez la section "Créer une branche depuis un Artifact" de la page Paramètres Git pour la procédure détaillée.

Contenu d’une Pull Request

Une fois créée, la PR s'ouvre sur l'onglet Résumé. La page est organisée en trois onglets : Résumé, Commits et Changements.

Onglet Résumé

L'onglet Résumé est le point central de la PR. Il affiche la description de la PR et l'ensemble de l'activité chronologique (timeline) : commentaires, changements d'état, mises à jour de code. C'est ici que se déroule la discussion entre le développeur et les relecteurs.

Le panneau latéral droit présente les métadonnées de la PR :

Auteur et date de création.
Relecteurs assignés à la revue.
Changements : nombre de lignes ajoutées et supprimées.
Statut intégration continue : badge indiquant le résultat du dernier build CI (Succès, Échec, En cours ou Inconnu).
Références : le SHA1 du commit et les branches source → destination.
Labels : étiquettes de catégorisation.

L'onglet Résumé retrace également les événements de cycle de vie de la PR : changements de relecteurs, mises à jour de branche (push de nouveaux commits), intégration, abandon ou réouverture. Chaque événement est horodaté et attribué à son auteur.

Onglet Commits

L'onglet Commits liste tous les commits inclus dans la PR. Chaque commit affiche son message, son auteur et la date.

Onglet Changements

L'onglet Changements affiche le diff de toutes les modifications apportées par la PR.

Un panneau latéral liste les fichiers modifiés, chacun accompagné d'un badge de statut :

M (Modifié) : le fichier existait déjà et a été modifié.
A (Ajouté) : le fichier a été créé dans cette PR.
D (Supprimé) : le fichier a été supprimé.

Chaque fichier affiche également le nombre de lignes ajoutées et supprimées, ce qui permet d'identifier rapidement l'ampleur des modifications.

Deux modes d'affichage du diff sont proposés :

Diff unifié : vue classique des lignes ajoutées et supprimées dans une seule colonne.
Diff côte à côte (side-by-side) : les suppressions à gauche, les ajouts à droite. Basculez entre les deux modes via le bouton dédié dans la barre d'outils.

Votre choix de mode d'affichage est enregistré dans vos préférences utilisateur et sera automatiquement appliqué lors de vos prochaines consultations.

Revue de code

Commentaires inline

Pour commenter une ligne spécifique du code, cliquez sur le numéro de la ligne dans l'onglet Changements. Un champ de saisie apparaît, vous permettant de laisser un commentaire contextuel. D'autres utilisateurs peuvent répondre, créant un fil de discussion (thread) sur cette ligne.

Les fils de discussion sont également visibles depuis l'onglet Résumé, regroupés dans la timeline.

Commentaires généraux

Depuis la section de commentaire en bas de l'onglet Résumé, vous pouvez ajouter des commentaires globaux sur la PR. Le champ de saisie propose deux modes : "Écrire" et "Aperçu", avec le support de la syntaxe Markdown.

Édition des commentaires

Vous pouvez modifier vos commentaires (globaux et inline) après les avoir publiés. Un indicateur de dernière modification est alors affiché à côté du commentaire, permettant aux autres participants de voir qu'il a été mis à jour.

Mentions @

Dans les commentaires et la description, mentionnez un utilisateur en tapant @ suivi de son nom. Un auto-compléteur apparaît après quelques caractères. L'utilisateur mentionné reçoit une notification email.

Relecteurs

Le champ "Relecteurs" du panneau latéral de l’onglet Résumé permet d'assigner les personnes chargées d'examiner le code. Cliquez sur l'icône d'édition pour rechercher un utilisateur par nom ou email (auto-complétion). Plusieurs relecteurs peuvent être assignés.

Chaque relecteur ajouté reçoit une notification email et son statut d'approbation est visible directement sur la PR.

Labels

Les PR peuvent être catégorisées à l'aide de labels définis au niveau du projet. Cliquez sur l'icône d'édition à côté de “Labels” dans l’onglet Résumé pour en assigner un ou plusieurs. Les labels sont ensuite utilisables comme critère de filtre dans la liste des PR.

Mise à jour et intégration

Mise à jour d'une Pull Request

Lorsque vous poussez de nouveaux commits sur la branche source, la PR est automatiquement mise à jour : les nouveaux commits apparaissent dans la timeline et le diff est recalculé.

Les commentaires inline existants qui portaient sur des lignes modifiées apparaissent alors grisés. Le commentaire reste visible, mais la ligne de code à laquelle il se réfère a changé.

Intégration

À la fin de la revue, deux boutons d'action sont disponibles en bas du panneau latéral :

"Intégrer" (vert) : fusionne les modifications de la branche source dans la branche destination.
"Abandonner" (rouge) : rejette la PR.

Information
Vous pouvez aussi fusionner manuellement en local et pousser le résultat. La PR sera automatiquement marquée comme intégrée.

Détection des conflits

Avant toute intégration, Tuleap vérifie automatiquement si la branche source peut être fusionnée dans la branche destination. Si des conflits sont détectés, le bouton "Intégrer" est désactivé et un message d'alerte vous invite à résoudre les conflits localement avant de mettre à jour la PR.

Tuleap distingue trois états de fusion :

Fast-forward possible : la branche destination est un ancêtre direct de la branche source. La fusion se fait sans commit de merge.
Fusion avec commit de merge : les deux branches ont divergé, mais aucun conflit n'est détecté. Un commit de fusion sera créé automatiquement.
Conflits détectés : les modifications se chevauchent et nécessitent une résolution manuelle. Récupérez la branche en local via le bouton Checkout, résolvez les conflits, puis poussez le résultat sur la branche source.

Attention
Lorsque la stratégie de fusion est réglée sur "Avance rapide uniquement" et que le fast-forward n'est pas possible, l'intégration est refusée même s'il n'y a pas de conflit. Vous devez dans ce cas rebaser votre branche sur la destination.

Réouverture d'une PR

Une PR abandonnée peut être réouverte à condition que les branches source et destination existent toujours dans le dépôt. Lors de la réouverture, Tuleap recalcule automatiquement le statut de fusion et prend en compte les éventuels nouveaux commits poussés entre-temps sur la branche source.

Les PR intégrées (fusionnées) ne peuvent pas être réouvertes.

Stratégie de fusion

L'administrateur du dépôt peut configurer la stratégie de fusion dans l'onglet "Pull requests" des paramètres du dépôt :

Par défaut : avance rapide (fast-forward) si possible, sinon création d'un commit de fusion.
Avance rapide uniquement : seul le fast-forward est autorisé. Si la branche n'est pas à jour, l'intégration est refusée.

Notifications

Email

Une notification email est envoyée automatiquement aux relecteurs, au créateur et aux contributeurs de la PR lors des événements suivants : mise à jour (nouveaux commits), intégration, abandon, ajout d'un commentaire (global ou inline). Les notifications ne sont pas envoyées à l'utilisateur qui effectue l'action.

Mattermost

Si le plugin Bot Mattermost Git est installé, les événements Git et Pull Requests (push, création, intégration, abandon) peuvent être relayés dans un canal Mattermost.

Information
La configuration se fait depuis l'administration des bots Mattermost du projet. Consultez la documentation Slack & Mattermost pour plus de détails.

Intégration continue (Jenkins)

Tuleap affiche le statut d'intégration continue directement sur la PR sous forme de badge. Quatre états sont possibles :

Succès : le build CI a réussi.
Échec : le build a échoué.
En cours : un build est actuellement en cours d'exécution.
Inconnu : aucun résultat CI n'est disponible.

La date du dernier build est affichée à côté du badge. Pour alimenter ce statut, configurez l'intégration Jenkins :

Ajoutez un webhook Jenkins dans les paramètres du dépôt Git (onglet Webhooks).
Dans le job Jenkins, configurez le refspec +refs/tlpr/*:refs/remotes/origin/pr/* et le branch specifier **.
Installez le plugin Tuleap API dans Jenkins pour que le résultat du build remonte automatiquement sur la PR.

Information
La configuration complète est décrite dans la documentation Pull request notification configuration.

Références croisées

Les Pull Requests participent pleinement au système de références croisées de Tuleap. Depuis la description ou les commentaires d'une PR, vous pouvez référencer n'importe quel élément Tuleap avec la syntaxe habituelle (par exemple art #123). Inversement, depuis n'importe quel endroit de Tuleap, utilisez pr #N ou pullrequest #N pour créer un lien vers une PR.

Les références croisées sont bidirectionnelles : créer une référence dans un sens crée automatiquement le lien retour.

Permissions

Les actions disponibles sur une Pull Request dépendent de vos droits sur le dépôt Git sous-jacent. Voici les principales règles d'accès :

Consulter une PR : tout utilisateur ayant accès en lecture au dépôt Git peut voir la PR et ses détails.
Créer une PR : tout utilisateur pouvant pousser du code sur le dépôt (ou sur un fork) peut créer une PR.
Commenter : tout utilisateur ayant accès en lecture peut poster des commentaires globaux et inline.
Modifier le titre et la description : réservé à l'auteur de la PR et aux administrateurs du dépôt.
Assigner des relecteurs :Il faut avoir le droit d'écriture sur la branche destination ou être le créateur de la pull request pour modifier la liste des relecteurs.
Gérer les labels : nécessite les droits de gestion des labels au niveau du projet.
Intégrer (fusionner) : réservé aux utilisateurs ayant les droits d'écriture sur la branche destination.
Abandonner : l'auteur de la PR et les utilisateurs ayant les droits d'écriture peuvent abandonner une PR.
Réouvrir : mêmes droits que pour l'abandon.

Information
Les administrateurs du projet et les administrateurs Git disposent de l'ensemble des permissions sur les Pull Requests de leurs dépôts.