Een pull-aanvraag doen

Een pull-aanvraag aanmaken

Pull-aanvragen zijn een functie waarmee ontwikkelaars eenvoudiger kunnen samenwerken in Bitbucket. Ze bieden een gebruiksvriendelijke webinterface voor het bespreken van voorgestelde wijzigingen voordat ze worden geïntegreerd in het officiële project.

Git-workflows: pull-aanvraag in Bitbucket

In hun eenvoudigste vorm zijn pull-aanvragen een mechanisme waarmee een ontwikkelaar teamleden op de hoogte kan stellen dat ze een functie hebben voltooid. Zodra hun functiebranch gereed is, dient de ontwikkelaar een pull-aanvraag in via zijn Bitbucket-account. Zo weten alle betrokkenen dat ze de code moeten controleren en moeten samenvoegen in de main-branch.

Maar de pull-aanvraag is meer dan alleen een melding: het is een speciaal forum om de voorgestelde functie te bespreken. Als er problemen met de wijzigingen zijn, kunnen teamgenoten feedback geven in de pull-aanvraag en zelfs de functie aanpassen door vervolg-commits te pushen. Al deze activiteiten worden rechtstreeks in de pull-aanvraag bijgehouden.

Git-workflows: activiteit in een pull-aanvraag

In vergelijking met andere samenwerkingsmodellen zorgt deze formele oplossing voor het delen van commits voor een veel gestroomlijnder workflow. SVN en Git kunnen beide automatisch e-mailmeldingen sturen met een eenvoudig script. Als het echter om het bespreken van wijzigingen gaat, zijn ontwikkelaars doorgaans afhankelijk van e-mailthreads. Dit kan een nogal lukraak proces worden, vooral als het om vervolg-commits gaat. Met pull-aanvragen zet je al deze functionaliteit in een gebruiksvriendelijke webinterface, direct naast je Bitbucket-repository's.

Anatomie van een pull-aanvraag

Als je een pull-aanvraag indient, vraag je alleen maar dat een andere ontwikkelaar (bijvoorbeeld de onderhouder van het project) een branch uit je repository naar zijn repository haalt. Dit betekent dat je vier soorten informatie moet opgeven om een pull-aanvraag in te dienen: de bron-repository, de bron-branch, de doel-repository en de doel-branch.

Git-workflow: pull-aanvragen

Veel van deze waarden zullen door Bitbucket op een logische standaardinstelling worden ingesteld. Afhankelijk van de manier waarop je samenwerkt kan het echter nodig zijn dat je team verschillende waarden specificeert. Het bovenstaande diagram toont een pull-aanvraag waarin wordt gevraagd om een functiebranch samen te voegen in de officiële main-branch, maar er zijn nog veel andere manieren om pull-aanvragen te gebruiken.

Hoe het werkt

Pull-aanvragen kunnen worden gebruikt in combinatie met de workflow voor functiebranches, de Gitflow-workflow of de workflow voor vertakking. Maar voor een pull-aanvraag zijn ofwel twee verschillende branches of twee verschillende repository's nodig. Ze zullen dus niet werken met de gecentraliseerde workflow. Het gebruik van pull-aanvragen voor elk van deze workflows is iets anders, maar het algemene proces is als volgt:

  1. Een ontwikkelaar maakt de functie in een speciale branch in zijn lokale repo;

  2. De ontwikkelaar pusht de branch naar een openbare Bitbucket-repository;

  3. De ontwikkelaar dient een pull-aanvraag in via Bitbucket;

  4. De rest van het team bekijkt de code, bespreekt deze en past deze aan;

  5. De projectbeheerder voegt de functie samen in de officiële repository en sluit de pull-aanvraag.

In de rest van dit gedeelte wordt beschreven hoe pull-aanvragen kunnen worden gebruikt voor verschillende samenwerkingsworkflows.

Workflow voor functiebranches met pull-aanvragen

De workflow voor functiebranches maakt gebruik van een gedeelde Bitbucket-repository voor het beheren van samenwerking. Ontwikkelaars maken functies in geïsoleerde branches. Maar in plaats van ze meteen samen te voegen in de main, zouden ontwikkelaars een pull-aanvraag moeten openen om een discussie over de functie te starten voordat deze in de main-codebase wordt geïntegreerd.

Pull-aanvraag: workflow voor functiebranches

Er is maar één openbare repository in de workflow voor functiebranches. De doel-repository van de pull-aanvraag en de bron-repository zullen dus altijd dezelfde zijn. Doorgaans specificeert de ontwikkelaar zijn functiebranch als de bron-branch en de main-branch als de doel-branch.

Na ontvangst van de pull-aanvraag moet de projectbeheerder beslissen wat hij gaat doen. Als de functie klaar is voor gebruik, kan deze eenvoudig worden samengevoegd in de main en kan de pull-aanvraag worden gesloten. Maar als er problemen met de voorgestelde wijzigingen zijn, kan de feedback in de pull-aanvraag worden geplaatst. De vervolgopdrachten worden direct naast de relevante opmerkingen weergegeven.

Het is ook mogelijk om een pull-aanvraag in te dienen voor een onvoltooide functie. Als een ontwikkelaar bijvoorbeeld problemen heeft met de uitvoering van een bepaalde vereiste, kan diegene een pull-aanvraag indienen met daarin het onderhanden werk. Andere ontwikkelaars kunnen dan suggesties doen in de pull-aanvraag, of zelfs het probleem zelf oplossen met aanvullende commits.

Gitflow-workflow met pull-aanvragen

De Gitflow-workflow is vergelijkbaar met de workflow voor functiebranches, maar definieert een strikt vertakkingsmodel dat is ontworpen rond de projectrelease. Door pull-aanvragen aan de Gitflow-workflow toe te voegen, kunnen ontwikkelaars op een handige plek praten over een release-branch of een onderhouds-branch terwijl ze eraan werken.

Pull-aanvragen: Gitflow-workflow Pull-aanvragen: Gitflow-workflow 2

Pull-aanvragen in de Gitflow-workflow werken exact hetzelfde als in de vorige sectie: een ontwikkelaar dient gewoon een pull-aanvraag in wanneer een functie-, release- of hotfix-branch moet worden beoordeeld. De rest van het team wordt vervolgens via Bitbucket op de hoogte gebracht.

Functies worden over het algemeen samengevoegd in de develop-branch, terwijl de release- en hotfix-branches worden samengevoegd tot zowel develop als main. Pull-aanvragen kunnen worden gebruikt om al deze samenvoegingen formeel te beheren.

Workflow voor vertakken met pull-aanvragen

In de workflow voor vertakking pusht een ontwikkelaar een voltooide functie naar zijn eigen openbare repository in plaats van naar een gedeelde repository. Daarna dient hij een pull-aanvraag in om de projectbeheerder te laten weten dat de functie klaar is voor beoordeling.

Het meldingsaspect van pull-aanvragen is bijzonder nuttig in deze workflow omdat de projectbeheerder op geen enkele manier kan weten wanneer een andere ontwikkelaar commits aan zijn Bitbucket-repository heeft toegevoegd.

Pull-aanvragen: workflow voor vertakking

Aangezien elke ontwikkelaar zijn eigen openbare repository heeft, zal de bron-repository van de pull-aanvraag verschillen van de doel-repository. De bron-repository is de openbare repository van de ontwikkelaar; de bron-branch bevat de voorgestelde wijzigingen. Als de ontwikkelaar probeert de functie in de hoofd-codebase samen te voegen, is de doel-repository het officiële project; de doel-branch is de main.

Pull-aanvragen kunnen ook worden gebruikt om samen te werken met andere ontwikkelaars buiten het officiële project. Als een ontwikkelaar bijvoorbeeld samen met een teamgenoot aan een functie werkt, kunnen ze een pull-aanvraag indienen met behulp van de Bitbucket-repository van de teamgenoot voor de bestemming in plaats van via het officiële project. Ze gebruiken dan dezelfde functiebranch voor de bron- en doel-branches.

Pull-aanvragen: workflow voor vertakking

De twee ontwikkelaars kunnen de functie in de pull-aanvraag bespreken en ontwikkelen. Als ze klaar zijn, dient een van hen nog een pull-aanvraag in met de vraag om de functie samen te voegen in de officiële main-branch. Dit soort flexibiliteit maakt pull-aanvragen tot een zeer krachtige tool voor samenwerking in de workflow voor vertakking.

Voorbeeld

Het onderstaande voorbeeld laat zien hoe pull-aanvragen in de workflow voor vertakking kunnen worden gebruikt. Het is evenzeer van toepassing op ontwikkelaars die in kleine teams werken als op een externe ontwikkelaar die bijdraagt aan een open source-project.

In dit voorbeeld is Mary een ontwikkelaar en onderhoudt John het project. Beide hebben hun eigen openbare Bitbucket-repository's. In die van John staat het officiële project.

Mary vertakt het officiële project

Pull-aanvragen: het project vertakken

Om aan het project te kunnen werken, moet Mary eerst een branch voor de Bitbucket-repository van John uitvoeren. Dit kan ze doen door zich bij Bitbucket aan te melden, naar de repository van John te gaan en op de knop Vertakken te klikken.

Pull-aanvragen: vertakken in Bitbucket

Nadat ze de naam en beschrijving van de vertakte repository heeft ingevuld, krijgt ze een kopie op de server van het project.

Mary kloont haar Bitbucket-repository

Pull-aanvraag: de Bitbucket-repo klonen

Vervolgens moet Mary de Bitbucket-repository klonen die ze net heeft vertakt. Zo krijgt ze een werkkopie van het project op haar lokale computer. Ze kan dit doen door de volgende opdracht uit te voeren:

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

Houd er rekening mee dat git clone automatisch een origin op afstand aanmaakt die terugverwijst naar de vertakte repository van Mary.

Mary ontwikkelt een nieuwe functie

Pull-aanvragen: een nieuwe functie ontwikkelen

Voordat ze code begint te schrijven, moet Mary een nieuwe branch aanmaken voor de functie. Deze branch zal ze gebruiken als bron-branch van de pull-aanvraag.

git checkout -b some-feature
# Edit some code
git commit -a -m "Add first draft of some feature"

Mary kan zoveel commits gebruiken als ze nodig heeft om de functie te maken. En als de geschiedenis van de functie rommeliger is dan ze zou willen, kan ze een interactieve rebase gebruiken om onnodige commits te verwijderen of te onderdrukken. Bij grotere projecten maakt het opschonen van de geschiedenis van een functie het veel eenvoudiger voor projectbeheerders om te zien wat er in de pull-aanvraag gebeurt.

Mary pusht de functie naar haar Bitbucket-repository

Pull-aanvragen: Een functie naar een Bitbucket-repository pushen

Nadat haar functie klaar is, pusht Mary de functiebranch naar haar eigen Bitbucket-repository (niet naar de officiële repository) met een simpele git push:

git push origin some-branch

Hierdoor zijn haar wijzigingen beschikbaar voor de beheerder van het project (of voor alle medewerkers die mogelijk toegang nodig hebben).

Mary maakt de pull-aanvraag aan

Pull-aanvraag: een pull-aanvraag aanmaken

Nadat Bitbucket haar functiebranch heeft ontvangen, kan Mary de pull-aanvraag aanmaken via haar Bitbucket-account door naar haar vertakte repository te navigeren en op de knop Pull-aanvraag in de rechterbovenhoek te klikken. Het resulterende formulier stelt Mary's repository automatisch in als bron-repository en vraagt haar om de bron-branch, de doel-repository en de doel-branch op te geven.

Mary wil haar functie samenvoegen in de belangrijkste codebase. De bron-branch is dus haar functiebranch, de doel-repository is de openbare repository van John en de doel-branch is main. Ze zal de pull-aanvraag ook een titel en beschrijving moeten geven. Als er naast John nog andere mensen zijn die de code moeten goedkeuren, kan ze die invoeren in het veld Beoordelaars.

Pull-aanvraag: Bitbucket

Nadat ze de pull-aanvraag heeft aangemaakt, wordt er een melding naar John gestuurd via zijn Bitbucket-feed en (optioneel) via e-mail.

John beoordeelt de pull-aanvraag

Pull-aanvragen: pull-aanvragen in Bitbucket

John heeft toegang tot alle pull-aanvragen die mensen hebben ingediend door op het tabblad Pull-aanvraag in zijn eigen Bitbucket-repository te klikken. Als hij op Mary's pull-aanvraag klikt, krijgt hij een beschrijving van de pull-aanvraag, de commit-geschiedenis van de functie en een overzicht van alle wijzigingen die erin zitten.

Als hij denkt dat de functie klaar is om in het project samen te voegen, hoeft hij alleen maar op de knop Samenvoegen te drukken om de pull-aanvraag goed te keuren en Mary's functie samen te voegen in zijn main-branch.

Maar laten we voor dit voorbeeld zeggen dat John een klein bug in Mary's code heeft gevonden, die ze moet oplossen voordat ze haar werk samenvoegt. Hij kan ofwel een opmerking plaatsen voor de pull-aanvraag in zijn geheel of hij kan een specifieke commit in de geschiedenis van de functie selecteren waarop ze moet reageren.

Pull-aanvraag: reageren

Mary voegt een vervolg-commit toe

Als Mary vragen over de feedback heeft, kan ze in de pull-aanvraag reageren en het behandelen als een discussieforum voor haar functie.

Om de fout te corrigeren, voegt Mary nog een commit toe aan haar functiebranch, die ze naar haar Bitbucket-repository pusht, net zoals ze de eerste keer deed. Deze commit wordt automatisch aan het oorspronkelijke pull-aanvraag toegevoegd, en John kan de wijzigingen direct naast zijn oorspronkelijke opmerking opnieuw bekijken.

John accepteert de pull-aanvraag

Tot slot accepteert John de wijzigingen, voegt hij de functiebranch samen in de main en sluit hij de pull-aanvraag af. De functie is nu geïntegreerd in het project en elke andere ontwikkelaar die eraan werkt, kan de functie naar zijn eigen lokale repository's ophalen met behulp van de standaard git pull-opdracht.

Hoe nu verder?

Je zou nu over alle tools moeten beschikken die je nodig hebt om pull-aanvragen in je bestaande workflow te integreren. Vergeet niet dat pull-aanvragen geen vervanging zijn voor een van de op Git gebaseerde samenwerkingsworkflows, maar eerder een handige aanvulling zijn die samenwerking toegankelijker maakt voor al je teamleden.

Klaar om pull-aanvragen uit te proberen?

Probeer deze interactieve tutorial.

Nu aan de slag