Effectieve pull-aanvragen en andere goede praktijken voor teams die github gebruiken — David Winterbottom (2023)

ik werk bijeen agentschapwaar we $ 200 per maand aan Github betalen voor hunplatina plan. Dit artikel is een samenvatting van een interne lezing die ik hield over het optimaal benutten van ons abonnement.

Er is hier niets origineels: het is gewoon een verzameling tips die ik de afgelopen jaren heb verzameld. Ik publiceer dit artikel vooral zodat ik iets heb om toekomstige werknemers naar te verwijzen.

Gebruik pull-aanvragen

Pull-verzoeken zijn een uitstekend hulpmiddel om codebeoordeling te bevorderen. Als je Github voor teamprojecten gebruikt, zou je deze uitgebreid moeten gebruiken.

Veel mensen realiseren zich niet dat je pull-requests kunt doen tussen twee branches van dezelfde repository (de zogenaamde“gedeeld repositorymodel”Voor teamprojecten verdient dit de voorkeur boven het ‘fork and pull’-model, omdat het eenvoudiger is: er zijn minder filialen en afstandsbedieningen om bij te houden.

Een goede gewoonte is dat iemand anders uw code in de hoofdregel samenvoegt, zodat twee sets oogbollen elke functie beoordelen. Dit is eenvoudig te organiseren als je met z'n tweeën werkt, maar in grotere teams heb je misschien een systeem nodig om te bepalen wie wat beoordeelt.

Voorbeeld van een werkstroom

Hier is een voorbeeldworkflow die het gebruik van pull-aanvragen demonstreert.

Werk aan een verhaal

Maak een nieuwe branch voor het huidige verhaal waar je aan werkt:

(meester)$ git checkout -b feature/masquerading

Het is om verschillende redenen belangrijk om een ​​nieuwe branch te gebruiken voor pull-aanvragen:

• Hiermee kunt u zonder verwarring meerdere pull-aanvragen indienen. De klassieke valkuil van Github is om door te gaan met committeren aan een pull request branch nadat het initiële verzoek is gedaan. Wanneer deze commits naar de afstandsbediening worden gepusht, worden ze onderdeel van het oorspronkelijke pull-verzoek, waardoor vaak niet-gerelateerde functionaliteit wordt samengevoegd.
• Wanneer je pull-verzoek wordt samengevoegd in de doelbranch, kan de beheerder beslissen om je commits opnieuw te baseren om een ​​merge-commit te voorkomen, of om de commits in één enkele samenhangende commit samen te vatten. Als je pull request afkomstig was van je ‘master’ branch, zul je problemen tegenkomen bij het mergen van de doel branch terug naar je eigen ‘master’. Het gebruik van een tijdelijke branch betekent dat deze kan worden weggegooid zodra het pull-verzoek is geaccepteerd en dat het er niet toe doet dat uw geschiedenis is herschreven.

Wijzigingen aanbrengen, tests uitvoeren, committen etc.

(functie/maskering)$ vim(functie/maskering)$ git commit

Vraag om feedback

Als het een belangrijk of moeilijk verhaal is, weet u misschien niet zeker of u op de goede weg bent. Je zou nu om wat feedback kunnen vragen door je commits naar daar te verplaatsen, zodat anderen deze kunnen beoordelen:

(functie/maskering)$ git push -u origin feature/masquerading

De-uoptie voegt een upstream tracking-referentie toe aan uw lokale branch, wat betekent dat u volgende push-commits kunt uitvoeren met behulp vangit pushzonder dat u de externe en filiaalnamen hoeft op te geven (en rungit trekkenzonder aanvullende argumenten).

Vraag nu om feedback over uw projectmailinglijst door een link naar het filiaal of een URL voor een vergelijkingsweergave te verspreiden. Je kunt uitstekend gebruik maken vanmiddelpuntom eenvoudig vergelijkings-URL's te genereren om te delen:

(meester)$ git vergelijk master..feature/masquerading

Hierdoor wordt uw standaardbrowser geopend op de vergelijkings-URL, die u vervolgens naar een e-mail kunt kopiëren.

Je mede-ontwikkelaars kunnen nu commentaar geven op je commits op regelniveau, of meer algemene opmerkingen maken door te reageren op de mailinglijstthread.

Pull-aanvraag indienen

Nadat u de opmerkingen van uw collega’s heeft verwerkt, past u uw aanpak aan en doet u nog meer engagement voor uw branche.

(functie/maskering)$ vim(functie/maskering)$ git commit

Wanneer het verhaal compleet is, push je je nieuwe commits naar de afstandsbediening:

(functie/maskering)$ git-push

en gebruik de Github-site om een ​​pull-aanvraag te maken. Een paar dingen waar u rekening mee moet houden:

• Zorg ervoor dat de doelvertakking correct is, deze is mogelijk niet altijd ‘master’. Als je git-flow of iets dergelijks gebruikt, kan de juiste bestemmingsvertakking 'develop' of een releasebranch zijn.
• Gebruik de preview-faciliteiten van Github om ervoor te zorgen dat het pull-verzoek goed gestructureerd en duidelijk is. De beschrijving moet uitleggen wat het pull-verzoek inhoudt, evenals de gedachte erachter. Ter referentie: kijk hier eens naaruitstekend trekverzoek.

Zodra het pull-verzoek is gemaakt, moet u iemand in uw team zoeken om het te beoordelen en hem/haar een link naar het verzoek sturen via de projectmailinglijst, zodat iedereen met interesse er naar kan kijken.

Codebeoordeling

Anderen kunnen nu uw branch beoordelen, commentaar geven op individuele regels of op het pull-verzoek als geheel: hetzelfde proces als toen u eerder een aantal commits ter beoordeling pushte.

Het is ook mogelijk voor anderen om commits toe te voegen aan het pull-verzoek door naar dezelfde branch te pushen:

(meester)$ git ophaaloorsprong(meester)$ git checkout-functie/masquerading(functie/maskering)$ vim(functie/maskering)$git toevoegen.(functie/maskering)$ git commit(functie/maskering)$ git push origin feature/masquerading

Herhaal dit totdat de vertakking klaar is om te worden samengevoegd.

Github easter egg: toevoegen?w=0om URL's te differentiëren (bijvoorbeeld een commit, een vergelijkingsweergave of een pull-verzoek) om witruimte te negeren.

Uw geschiedenis opschonen (optioneel)

Wanneer u klaar bent om samen te voegen, moet u eerst de feature branch opruimen.

Als er commits op de bestemmingsbranch zijn die niet op jouw featurebranch staan, dan moet je rebaseen om een ​​merge-commit te voorkomen. Je kunt dergelijke commits controleren met behulp van:

(functie/maskering)$ git log ..master

Dit toont alle commits op ‘master’ die niet in je huidige branchgeschiedenis staan. Als je hier commits ziet, rebase dan de feature branch met:

(functie/maskering)$ git rebase-master

Dit herhaalt jouw commits bovenop de nieuwe commits van de doelvertakkingen, zodat de samenvoeging ‘fast-forward’ kan zijn.

Wacht even! Ben je niet de geschiedenis aan het herschrijven die gepusht is? Ja dat is waar. Wanneer de externe vestiging echter istijdelijkwat betreft een pull-verzoek, dit is oké (voor zover ik weet). De pull request branch moet worden verwijderd zodra deze is samengevoegd en het zou er dus niet toe moeten doen dat de geschiedenis ervan wordt herschreven voordat deze is samengevoegd.

Vervolgens kan het wenselijk zijn om je commits op te delen in grotere, samenhangende commits. Je kunt dit doen met behulp van een ‘interactieve’ rebase:

(functie/maskering)$ git rebase -i master

Deze gaat open$REDACTIEmet alle commits sinds ‘master’ vermeld. Je kunt deze commits vervolgens opnieuw rangschikken en vernietigen, en ook de commit-berichten herformuleren. Pas op, dit kan behoorlijk verslavend zijn.

Eén ding dat je kunt doen is het laatste commit-bericht op je feature branch aanpassen, zodat het pull-verzoek automatisch wordt gesloten. Voeg eenvoudig ‘Fixes #123’ toe (met behulp van de ID van de pull-request-URL) onderaan het bericht.

(functie/maskering)$ git commit --amend

Verder lezen:

• Github geeft 2.0 uit: de volgende generatie-Een overzicht van Github-problemen met een uitleg over het sluiten, heropenen en verwijzen naar pull-aanvragen vanuit commit-berichten.
• Github-hulp: rebasen
• Github-hulp: interactief rebasen

Samenvoegen

Ten slotte kun je je opgeschoonde feature branch samenvoegen met een snelle samenvoeging:

(functie/maskering)$ git checkout-master(meester)$ git merge-functie/masquerading

Als alternatief kun je een merge commit forceren om bij te houden welke commits uit de feature branch kwamen.

(functie/maskering)$ git checkout-master(meester)$ git merge --no-ff feature/masquerading

Wanneer u uw geschiedenis als een grafiek bekijkt, kunt u zien welke commits afkomstig waren uit de feature branch.

Verwijder nu de lokale en externe functievertakkingen:

(meester)$ git branch -D feature/masquerading(meester)$ git push oorsprong: feature/masquerading

Verder lezen:

• Het gebruik van pull-requests

Andere goede praktijken

Geef om je geschiedenis

Streef naar een zuivere, samenhangende geschiedenis. Schrijvengoede commit-berichten, met inachtneming van de samenvatting van 50 tekens, gevolgd door een langere beschrijving. Vermijd onnodige merge-commits, aangezien deze uw geschiedenis onoverzichtelijk maken.

Zoals we hierboven zagen, kun je, als je je branch niet naar een stabiele, externe branch hebt gepusht, deze herschrijven:

• Gebruikgit rebaseom je feature branch opnieuw te baseren op de branch waarin je wilt mergen. Dit betekent dat wanneer je merget, het een zogenaamde ‘fastforward’ merge zal zijn, waardoor een merge commit wordt vermeden.
• Gebruikgit rebase -iom de geschiedenis van uw branch te herschrijven, gerelateerde commits te vernietigen, commit-berichten te herformuleren.

Bouw een audittrail

Probeer een goed audittraject op te bouwen - uw toekomstige zelf zal u dankbaar zijn. Verwijs waar mogelijk naar andere bronnen in uw commit-berichten. Deze kunnen zijn:

• Github pull-verzoeken of problemen (bijvoorbeeld “Gerelateerd aan #123”)
• Mailinglijstthreads waarin het betreffende werk wordt besproken (probeer mailinglijstsoftware te gebruiken waarmee u naar een discussie kunt linken). Als u Basecamp of iets dergelijks gebruikt, link dan naar de relevante discussie.
• Artikelen of blogposts die relevant zijn voor uw werk

Eigenlijk alles wat twaalf maanden later van pas kan komen als je de redenering achter een bepaald onderdeel probeert te achterhalen.

Eén ding probeer ik mee te doendjango-oscar(een project van mij) is het bijhouden van een audit trail vanaf een commit helemaal terug naar de mailinglijstdiscussie die er de aanleiding voor was. Dit werkt als volgt:

• Als je verbaasd bent over een bepaalde regel in een bestand, gebruik dangeef de schuldom de commit te vinden die het heeft geïntroduceerd.
• Het commit-bericht moet de wijziging uitleggen die tot deze regel heeft geleid en een link naar een pull-verzoek.
• Het pull-verzoek moet een reeks gerelateerde commits zijn die samen een nieuwe functie implementeren. De beschrijving van het pull-verzoek moet een functionele specificatie zijn voor de betreffende functie, samen met een link naar de mailinglijstthread waar deze functie werd besproken.

Ik volg dit proces nog niet zo lang, maar het lijkt goed te werken.

Gebruik uw aanwijzing

Zet relevante git-informatie in je prompt - dit zal je leven gemakkelijker maken. Hier is een bash-fragment voor het toevoegen van de huidige git branch aan je prompt:

# ~/.bashrcfunctieparse_git_branch{git branch --no-color 2> /dev/null | sed-e'/^[^*]/d'-e's/* \(.*\)/(\1) /'}PS1="\[\e[32m\]\$(parse_git_branch)\[\e[34m\]\h:\W \$ \[\e[m\]"PS1 exporteren

Gebruik aliassen voor snelheid

Probeer zo productief mogelijk te zijn op de commandoregel. Voor mij betekent dat het minimaliseren van toetsaanslagen.

Met git kun je zowel git- als bash-aliassen definiëren om je leven gemakkelijker te maken. Ik heb veel (hieronder vermeld). Er zijn er twee die de moeite waard zijn om te benadrukken:

1. Ik aliasgit-status -sbnaarGzodat ik snel de git-status kan controleren. Dit is mijn meest vaak getypte commando, dus het is logisch om het gemakkelijk te maken.
2. Net als vele anderen gebruik ik een aangepaste versie vangit logwaarin één commit per regel wordt vermeld, maar geannoteerd met andere nuttige informatie, zoals naar welke commits andere takken verwijzen. Zie de definitie vangit geschiedenisonderstaand.

Geselecteerde aliassen van~/.gitconfig:

[alias] geschiedenis = log --color --pretty=format:\"%C(geel)%h%C(reset) %s%C(vet rood)%d%C(reset) %C(groen)%ad%C(reset ) %C(blauw)[%an]%C(reset)\" --relatieve-datum --versierunstage = reset HEAD --herstellen = afrekenen --cn = commit --no-verifyco = afrekenenlof = schuldvisualiseer = !gitkgrafiek = log --kleur --grafiek --pretty=format:\"%h | %ad | %an | %s%d\" --datum=kort

En van~/.bash_aliases:

alias git='middelpunt'alias g='git-status -sb'alias g='git geschiedenis'alias gp='git trekken'alias gpr='git pull --rebase'oftewel gpp='git pull --rebase && git push'alias gf='git ophalen'oftewel GB='git tak'alias ga='git toevoegen'alias gc='git commit'gca alias='git commit --amend'alias gcv='git commit --no-verify'alias gd='git diff --color-woorden'alias gdc='git diff --cached -w'oftewel gdw='git diff --no-ext-diff --word-diff'oftewel gdv='git diff'alias gl='git log --oneline --decorate'alias gt='git-tag'alias grc='git rebase --doorgaan'alias grs='git rebase --skip'alias gsl='git stashlijst'alias gss='git stash opslaan'