Faire une pull request

Faire une pull request

Les pull requests sont une fonctionnalité facilitant la collaboration des développeurs avec Bitbucket. Elles fournissent une interface Web conviviale pour discuter des changements proposés avant de les intégrer au projet officiel.

Workflows Git : Pull request dans Bitbucket

Dans leur forme la plus élémentaire, les pull requests sont un mécanisme qui permet à un développeur de prévenir les membres de son équipe qu'il a terminé une fonctionnalité. Une fois que sa branche de fonctionnalité est prête, le développeur fait une pull request via son compte Bitbucket. Ainsi, toutes les personnes concernées sont informées du fait qu'elles doivent réviser le code et l'intégrer à la branche master.

La pull request est plus qu'une simple notification : il s'agit d'un forum dédié pour discuter de la fonctionnalité proposée. Si les changements posent problème, les membres de votre équipe peuvent donner du feedback dans la pull request et adapter la fonctionnalité en pushant des commits de suivi. Cette activité est directement suivie dans la pull request.

Workflows Git : activité au sein d'une pull request

Par rapport à d'autres modèles de collaboration, cette solution formelle de partage des commits simplifie considérablement le workflow. SVN et Git peuvent envoyer automatiquement des e-mails de notification avec un script simple. Cependant, pour discuter des changements, les développeurs communiquent généralement par e-mail. Cela peut donner lieu à des incohérences, notamment en raison des commits de suivi. Les pull requests offrent cette fonctionnalité dans une interface Web conviviale juste à côté de vos dépôts Bitbucket.

Structure d'une pull request

Lorsque vous faites une pull request, vous demandez simplement à un autre développeur (par ex., le mainteneur de projet) de faire un pull d'une branche de votre dépôt vers le sien. Autrement dit, vous avez besoin de quatre informations pour faire une pull request : le dépôt source, la branche source, le dépôt cible et la branche cible.

Workflows Git : Pull requests

Bitbucket définit la plupart des valeurs sur une valeur sensible par défaut. Toutefois, votre équipe devra peut-être spécifier des valeurs différentes en fonction de votre workflow de collaboration. Le schéma ci-dessus illustre une pull request qui demande à faire un merge d'une branche de fonctionnalité avec la branche master officielle. Mais les pulls requests peuvent être utilisées de bien d'autres façons.

Fonctionnement

Les pull requests peuvent être utilisées avec le workflow de branche par fonctionnalité, le workflow Gitflow ou le workflow de duplication (fork). Toutefois, une pull request nécessite deux branches ou deux dépôts distincts, elle ne fonctionnera donc pas avec le workflow centralisé. L'utilisation des pull requests avec ces workflows présente de légères différences, mais le processus général est le suivant :

  1. Un développeur crée la fonctionnalité dans une branche dédiée de son dépôt local.

  2. Le développeur pushe la branche vers un dépôt Bitbucket public.

  3. Le développeur fait une pull request via Bitbucket.

  4. Le reste de l'équipe révise le code, en discute, puis le modifie.

  5. Le mainteneur de projet fait un merge de la fonctionnalité dans le dépôt officiel, puis ferme la pull request.

Le reste de la section décrit comment les pull requests peuvent être exploitées dans les différents workflows de collaboration.

Workflow de branche par fonctionnalité avec pull requests

Le workflow de branche par fonctionnalité utilise un dépôt Bitbucket partagé pour gérer la collaboration, et les développeurs créent des fonctionnalités dans des branches isolées. Toutefois, au lieu d'en faire immédiatement un merge dans la branche master, les développeurs doivent faire une pull request pour initier une discussion sur la fonctionnalité avant que celle-ci ne soit intégrée à la base de code principale.

Pull request : workflow de branche par fonctionnalité

Le workflow de branche par fonctionnalité compte un seul dépôt public. Par conséquent, le dépôt source et le dépôt cible de la pull request resteront inchangés. En règle générale, le développeur définit la branche de fonctionnalité comme la branche source et la branche master, comme la branche cible.

Après réception de la pull request, le mainteneur de projet devra déterminer la marche à suivre. Si la fonctionnalité est prête, il suffira simplement de faire un merge dans la branche master et de fermer la pull request. Cependant, si les changements proposés ne sont pas valides, le mainteneur de projet donnera son feedback dans la pull request. Les commits de suivi s'afficheront en regard des commentaires concernés.

Une pull request peut aussi être faite pour une fonctionnalité incomplète. Par exemple, si un développeur rencontre certaines difficultés pour répondre à une exigence particulière, il peut faire une pull request qui contient ses travaux en cours. D'autres développeurs peuvent ensuite proposer des suggestions dans la pull request, voire résoudre le problème eux-mêmes avec des commits supplémentaires.

Workflow Gitflow avec pull requests

Le workflow Gitflow est similaire au workflow de branche par fonctionnalité, mais il définit un modèle de création de branche strict conçu autour de la livraison du projet. En ajoutant des pull requests au workflow Gitflow, les développeurs peuvent discuter des branches de livraison ou de maintenance alors qu'ils y travaillent.

Pull requests : Workflow Gitflow Pull requests : Workflow Gitflow 2

Dans le workflow Gitflow, les pull requests fonctionnent de la même façon que ce que nous venons de voir : un développeur fait simplement une pull request lorsqu'une branche de fonctionnalité, release ou hotfix doit être vérifiée. Le reste de l'équipe en est ensuite averti par Bitbucket.

Les fonctionnalités sont généralement mergées dans la branche develop, tandis que les branches release et hotfix sont mergées dans develop et master. Les pull requests peuvent être utilisées pour gérer tous ces merges.

Workflow de duplication (fork) avec pull requests

Dans le workflow de duplication (fork), un développeur pushe une fonctionnalité complète vers son propre dépôt public et non vers un dépôt partagé. Ensuite, il fait une pull request pour informer le mainteneur de projet que la fonctionnalité peut être révisée.

Les pull requests ont une fonction de notification particulièrement utile dans ce workflow, car le mainteneur de projet n'a aucun moyen de savoir à quel moment un autre développeur a ajouté des commits dans le dépôt Bitbucket.

Pull requests : Workflow de duplication (fork)

Comme chaque développeur dispose de son propre dépôt public, le dépôt source de la pull request différera de son dépôt cible. Le dépôt source constitue le dépôt public du développeur, et la branche source contient les changements proposés. Si le développeur tente de merger la fonctionnalité dans la base de code principale, le dépôt cible deviendra le projet officiel, et la branche cible se nommera master.

Les pull requests permettent également de collaborer avec des développeurs hors du projet officiel. Par exemple, si un développeur travaillait sur une fonctionnalité avec un membre de son équipe, il peut faire une pull request avec le dépôt Bitbucket de ce membre comme dépôt cible au lieu du projet officiel. Il peut ensuite utiliser cette branche de fonctionnalité comme branche source et cible.

Pull requests : Workflow de duplication (fork)

Les deux développeurs peuvent discuter de la fonctionnalité et la développer dans la pull request. Lorsqu'ils ont terminé, l'un d'entre eux peut créer une autre pull request demandant de faire un merge de la fonctionnalité dans la branche master officielle. Cette flexibilité fait des pull requests un outil de collaboration précieux dans le workflow de duplication (fork).

Exemple

L'exemple suivant présente une utilisation des pull requests dans le workflow de duplication (fork). Cela est également valable pour les développeurs qui travaillent dans de petites équipes et pour les développeurs tiers qui contribuent à un projet open source.

Dans cet exemple, Marie est développeuse et Jean est mainteneur de projet. Tous deux disposent de leur propre dépôt Bitbucket public et celui de Jean contient le projet officiel.

Marie fait un fork du projet officiel.

Pull requests : Faire un fork dans le projet

Pour commencer à travailler dans le projet, Marie doit d'abord faire un fork du dépôt Bitbucket de Jean. Pour cela, elle doit se connecter à Bitbucket, accéder au dépôt de Jean, puis cliquer sur le bouton Fork.

Pull requests : Faire un fork dans Bitbucket

Après avoir renseigné le nom et la description du dépôt forké, elle disposera d'une copie du projet côté serveur.

Marie clone son dépôt Bitbucket

Pull requests : Cloner le dépôt Bitbucket

Marie doit ensuite cloner le dépôt Bitbucket qu'elle vient de forker. Elle disposera ainsi d'une copie de travail du projet sur son ordinateur local. Pour ce faire, elle peut exécuter la commande suivante :

git clone https://user@bitbucket.org/user/repo.git

Gardez à l'esprit que la commande git clone crée automatiquement un dépôt distant origin qui pointe vers le dépôt forké de Marie.

Marie développe une nouvelle fonctionnalité.

Pull requests : Développer une nouvelle fonctionnalité

Avant de commencer à programmer, Marie doit créer une nouvelle branche pour la fonctionnalité. Cette branche servira de branche source pour la pull request.

git checkout -b some-feature
# Vous éditez le code
git commit -a -m "J'ai ajouté la première ébauche d'une fonctionnalité donnée"

Marie peut utiliser autant de commits que nécessaire pour créer la fonctionnalité. En outre, si l'historique de la fonctionnalité est plus désordonné qu'elle le voudrait, elle peut utiliser un rebase interactif pour supprimer ou faire un squash des commits inutiles. Pour les projets plus importants, le nettoyage de l'historique d'une fonctionnalité permet au mainteneur de projet de voir plus facilement ce qu'il se passe dans la pull request.

Marie pushe la fonctionnalité vers son dépôt Bitbucket.

Pull requests : Pusher la fonctionnalité vers le dépôt Bitbucket

Une fois que Marie aura terminé de développer sa fonctionnalité, elle n'aura plus qu'à pusher la branche concernée vers son propre dépôt Bitbucket (et non vers le dépôt officiel) grâce à la commande git push :

git push origin some-branch

Les changements qu'elle a effectués seront ensuite disponibles pour le mainteneur de projet (ou pour les collaborateurs qui pourraient avoir besoin d'y accéder).

Marie crée la pull request

Pull requests : Créer une pull request

Lorsque Bitbucket contient sa branche de fonctionnalité, Marie peut créer la pull request via son compte Bitbucket en accédant à son dépôt forké, puis en cliquant sur le bouton Pull request dans le coin supérieur droit. Le formulaire obtenu définit automatiquement le dépôt de Marie comme dépôt source, puis lui demande de spécifier la branche source, le dépôt cible et la branche cible.

Marie souhaite merger sa fonctionnalité dans la base de code principale. Par conséquent, la branche source est sa branche de fonctionnalité, le dépôt cible est le dépôt public de Jean et la branche cible est la branche master. Elle devra également ajouter un titre et une description à la pull request. Si d'autres personnes que Jean doivent approuver le code, elle peut saisir leur nom dans le champ Reviewers (Réviseurs).

Pull requests : Bitbucket

Lorsqu'elle a créé la pull request, une notification est envoyée à Jean via son flux Bitbucket et, facultativement, par e-mail.

Jean révise la pull request.

Pull requests : Pull requests Bitbucket

Jean peut accéder à toutes les pull requests crées en cliquant sur l'onglet Pull request de son propre dépôt Bitbucket. Lorsqu'il clique sur la pull request de Marie, il voit la description de la pull request, l'historique des commits de la fonctionnalité et une comparaison de tous les changements qu'il contient.

Si Jean estime que la fonctionnalité est prête à être mergée dans le projet, il lui suffit d'appuyer sur le bouton Merge pour approuver la pull request et merger la fonctionnalité de Marie dans sa branche master.

Mais, pour cet exemple, supposons que Jean trouve un petit bug dans le code de Marie et qu'elle doive le corriger avant de faire le merge. Il peut publier un commentaire sur la pull request dans sa globalité ou il peut choisir un commit spécifique dans l'historique de la fonctionnalité pour le commenter.

Pull request : commentaire

Marie ajoute un commit de suivi.

Si Marie a des questions sur le feedback, elle peut répondre dans la pull request et s'en servir comme d'un forum de discussion sur sa fonctionnalité.

Pour corriger l'erreur, Marie ajoute un autre commit dans sa branche de fonctionnalité et le pushe vers son dépôt Bitbucket, tout comme elle l'a fait la première fois. Ce commit est automatiquement ajouté dans la pull request d'origine, et Jean peut consulter les changements en regard de son commentaire d'origine.

Jean accepte la pull request.

Enfin, Jean accepte les changements, merge la branche de fonctionnalité dans la branche master, puis ferme la pull request. La fonctionnalité est à présent intégrée au projet, et tout autre développeur qui travaille dessus peut l'ajouter à ses dépôts locaux en exécutant la commande standard git pull.

Marche à suivre

Vous devriez désormais disposer de tous les outils dont vous avez besoin pour commencer à intégrer des pull requests à votre workflow existant. N'oubliez pas, les pull requests ne remplacent pas les workflows de collaboration Git, mais les complètent afin de rendre la collaboration plus accessible à tous les membres de votre équipe.

Prêt à essayer les pull requests ?

Essayez ce tutoriel interactif.

Démarrez maintenant