Git
Chapters ▾ 2nd Edition

6.2 GitHub - Aan een project bijdragen

Aan een project bijdragen

Nu het account is ingericht, laten we eens door de details lopen die je kunnen helpen bij het bijdragen bij bestaande projecten.

Projecten afsplitsen (forken)

Als je wilt bijdragen aan een bestaand project waar je geen push toegang tot hebt, kan je het project “forken”. Dat houdt in dat GitHub je een kopie laat maken van het project die geheel van jouw is; het bestaat in de namespace van jouw gebruiker en jij kunt ernaar pushen.

Noot

Historisch gezien is de term “fork” een beetje negatief in context, in die zin dat iemand een open source project in een andere richting leidde, soms een concurrerend project makend en de bijdragers onderling verdeelde. In GitHub is een “fork” eenvoudigweg hetzelfde project in jouw namespace, wat jou toestaat om wijzigingen aan een project openbaar te maken met als doel om op een meer open manier bij te dragen.

Op deze manier hoeven projecten zich geen zorgen te maken over gebruikers als bijdragers toe te voegen om ze push-toegang te geven. Mensen kunnen een project forken, ernaar pushen, en hun wijzigingen terug naar de oorspronkelijke project bij te dragen door een zogenoemde Pull Request te maken, wat we straks zullen behandelen. Dit opent een discussie thread met code review en de eigenaar en de bijdrager kunnen dan over de wijziging communiceren totdat de eigenaar ermee tevreden is, op welk moment de eigenaar deze kan mergen.

Om een project te forken, bezoek je de projectpagina en klikt op de “Fork” knop rechtboven op de pagina.

De ``Fork'' knop.
Figuur 89. De “Fork” knop.

Na enkele seconden zal je naar jouw nieuwe projectpagina worden geleid, met je eigen schrijfbare kopie van de code.

De GitHub flow

GitHub is ontworpen rond een specifieke samenwerkings workflow die draait om pull-verzoeken (Pull Requests). Deze workflow werkt of je nu samenwerkt met een hecht team in een enkel gedeelde repository of een bedrijf dat wereldwijd verspreid is of een netwerk van onbekenden die bijdragen aan een project door middel van vele forks. Het is gericht op de Topic branches workflow die behandeld is in Branchen in Git.

Hier is hoe het over het algemeen werkt:

  1. Fork het project

  2. Maak een topic branch van master.

  3. Doe een aantal commits om het project te verbeteren.

  4. Push deze branch naar jouw GitHub project.

  5. Open een Pull Request op GitHub.

  6. Bespreek en blijf committen zo je wilt.

  7. De project eigenaar merget of sluit de Pull Request.

  8. Synchroniseer de geupdate master terug naar je fork

Dit is eigenlijk de Integratie Manager workflow zoals deze behandeld is in Integratie-manager workflow, maar in plaats van mail te gebruiken om te communiceren en wijzigingen te reviewen, gebruiken teams de web-gebaseerde instrumenten van GitHub.

Laten we eens een voorbeeld bespreken van een voorstel tot wijziging aan een open source project die op GitHub gehost wordt die deze workflow gebruikt.

Een Pull Request maken

Tony is op zoek naar code om op zijn Arduino programmeerbare microcontroller te draaien en heeft een fantastisch project gevonden op GitHub op https://github.com/schacon/blink.

Het project waar we aan willen bijdragen.
Figuur 90. Het project waar we aan willen bijdragen.

Het enige probleem is dat het lichtje te snel knippert. We vinden dat het veel beter is als we 3 seconden wachten in plaats van 1 tussen elke status wijziging. Laten we dus het programma verbeteren en het terugsturen aan het project als een wijzigingsvoorstel.

Eerst klikken we de Fork knop zoals eerder gezegd om onze eigen kopie van het project te krijgen. Onze gebruikersnaam is in dit geval “tonychacon” dus onze kopie van dit project is op https://github.com/tonychacon/blink en dat is waar we het kunnen wijzigen. We clonen het lokaal, maken een topic branch en doen de codewijziging en tot slot pushen we de wijziging weer naar GitHub.

$ git clone https://github.com/tonychacon/blink (1)
Cloning into 'blink'...

$ cd blink
$ git checkout -b slow-blink (2)
Switched to a new branch 'slow-blink'

$ sed -i '' 's/1000/3000/' blink.ino (macOS) (3)
# If you're on a Linux system, do this instead:
# $ sed -i 's/1000/3000/' blink.ino (3)

$ git diff --word-diff (4)
diff --git a/blink.ino b/blink.ino
index 15b9911..a6cc5a5 100644
--- a/blink.ino
+++ b/blink.ino
@@ -18,7 +18,7 @@ void setup() {
// the loop routine runs over and over again forever:
void loop() {
  digitalWrite(led, HIGH);   // turn the LED on (HIGH is the voltage level)
  [-delay(1000);-]{+delay(3000);+}               // wait for a second
  digitalWrite(led, LOW);    // turn the LED off by making the voltage LOW
  [-delay(1000);-]{+delay(3000);+}               // wait for a second
}

$ git commit -a -m 'three seconds is better' (5)
[slow-blink 5ca509d] three seconds is better
 1 file changed, 2 insertions(+), 2 deletions(-)

$ git push origin slow-blink (6)
Username for 'https://github.com': tonychacon
Password for 'https://tonychacon@github.com':
Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 340 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To https://github.com/tonychacon/blink
 * [new branch]      slow-blink -> slow-blink
  1. Kloon onze fork van het project lokaal

  2. Maak een omschrijvende topic branch

  3. Voer onze wijzigingen ana de code uit

  4. Controleer dat de wijziging juist is

  5. Commit de wijziging naar de topic branch

  6. Push onze nieuwe topic branch terug naar onze GitHub fork

Als we nu teruggaan naar onze fork op GitHub, kunnen we zien dat GitHub heeft opgemerkt dat we een nieuwe topic branch hebben gepusht en laat ons een grote groene knop zien om onze wijzigingen te bekijken en een Pull Request te openen naar het oorspronkelijke project.

Als alternatief zou je naar de “Branches” pagina kunnen gaan op https://github.com/<user>/<project>/branches en jouw branch opzoeken en een Pull Request vanuit die locatie openen.

Pull Request knop
Figuur 91. Pull Request knop

Als we op die groene knop klikken, zullen we een scherm zien die ons in staat stelt een titel en een omschrijving voor de wijziging die we willen aanvragen. Het is over het algemeen een goed idee om wat moeite te steken in het maken van een zo goed mogelijke omschrijving zodat de eigenaar van het originele project weet waarom dit wordt gesuggereert, dat je wijziging correct is, en waarom het een waardevolle wijziging is als deze wordt geaccepteerd.

We zien ook een lijst van de commits in onze topic branch die “voorlopen” op de master-branch (in dit geval, alleen deze ene) en een unified diff van alle wijzigingen die gemaakt zullen worden als deze branch gemerged gaat worden door de project eigenaar.

Pull Request aanmaak
Figuur 92. Pull Request aanmaak pagina

Als je op de Create pull request knop drukt op deze pagina, zal de eigenaar van het project waar jij vanaf hebt geforked een berichtje krijgen dat iemand een wijziging voorstelt en zal naar een pagina verwijzen waar al deze informatie op vermeld staat.

Noot

Alhoewel Pull Requests gewoonlijk gebruikt worden voor openbare projecten zoals deze als de bijdrager een volledige wijziging klaar heeft staan, is het ook vaak gebruikt in interne projecten aan het begin van de ontwikkel-cyclus. Omdat je kunt blijven pushen naar de topic branch zelfs nadat de Pull Request is geopend, wordt deze vaak vroeg geopend en gebruikt als een manier om op werk te itereren als een team binnen een context, in plaats van te worden geopend helemaal aan het eind van het proces.

Iteraties op een Pull Request

Op dit moment kan de project eigenaar naar de voorgedragen wijziging kijken en deze mergen, afwijzen of er op reageren. Laten doen alsof het idee hem aanspreekt, maar dat hij het lichtje iets langer uit wil hebben dan aan.

Waar deze discussie via mail zou kunnen plaatsvinden in de workflows die we hebben laten zien in Gedistribueerd Git, heeft het bij GitHub online plaats. De project eigenaar kan de unified diff bekijken en een commentaar achterlaten door op een of meer regels te klikken.

PR regel commentaar
Figuur 93. Commentariëren op een specifieke code regel in een Pull Request

Als de onderhouder dit commentaar eenmaal heeft gemaakt zal de persoon die de Pull Request heeft geopend (en verder iedereen die deze repository volgt) een berichtje krijgen. We zullen straks de manier waarop dit kan worden aangepast behandelen, maar als hij email notificaties aan heeft staan, zou Tony een mail zoals deze krijgen:

E-mail notificatie
Figuur 94. Commentaar verstuurd als email notificaties

Het is iedereen toegestaan om algemene commentaren op het Pull Request te maken. In Pull Request discussie pagina kunnen we een voorbeeld zien van de project eigenaar die zowel een regel code becommentariëert en daarna een algemeen commentaar achterlaat in het discussie gedeelte. Je kunt zien dat de code commentaren ook in de conversatie worden gevoegd.

PR discussie pagina
Figuur 95. Pull Request discussie pagina

Nu kan de bijdrager zien wat hij moet doen om hun wijziging geaccepteerd te krijgen. Gelukkig is dit ook erg eenvoudig om te doen. Waar je bij email je reeks opnieuw moet samenstellen en opnieuw submitten naar de mail lijst, hoef je met GitHub alleen opnieuw naar de topic branch te committen en te pushen. In Pull Request finaal is te zien dat de oude code commentaar is ingeklapt in de bijgewerkte Pull Request, omdat deze is gemaakt dat sindsdien is gewijzigd.

Het toevoegen van commits in een bestaande Pull Request veroorzaakt geen notificatie, dus als Tony eenmaal zijn correcties heeft gepusht besluit hij om een commentaar achter te laten om de project eigenaar te informeren dat hij de gevraagde wijziging gemaakt heeft.

PR finaal
Figuur 96. Pull Request finaal

Een interessant iets om op te merken is dat wanneer je de “Files Changed” tab klikt op deze Pull Request, je de “unified” diff krijgt —  daarmee wordt het uiteindelijke geaggregeerde verschil bedoeld die geintroduceerd wordt met je hoofd branch als deze topic branch zou zijn gemerged. In git diff terminologie, het laat feitelijk automatisch de git diff master...<branch> zien voor de branch waar deze Pull Request op is gebaseerd. Zie Bepalen wat geïntroduceerd is geworden voor meer informatie over dit type diff.

Het andere wat je zult zien is dat GitHub controleert of de Pull Request goed zou mergen en een knop biedt om de merge voor je te doen op de server. Deze knop krijg je alleen te zien als je schrijf-rechten hebt op de repository en een triviale merge mogelijk is. Als je de knop klikt zal GitHub een “non-fast-forward” merge uitvoeren, wat inhoudt dat zelfs als de merge een fast-forward zou kunnen zijn, het nog steeds een merge commit maakt.

Als je dat liever hebt, kan je de branch eenvoudigweg pullen en het lokaal mergen. Als je deze branch merget in de master-branch en deze naar GitHub pusht, wordt de Pull Request automatisch gesloten.

Dit is de eenvoudige workflow dat de meeste GitHub projecten gebruiken. Topic branches worden gemaakt, Pull Requests worden hierop geopend, een discussie volgt, mogelijk wordt er meer werk op de branch gedaan en uiteindelijk wordt het request gesloten of gemerged.

Noot
Niet alleen forks

Het is belangrijk op te merken dat je ook een Pull Request kunt openen tussen twee branches in dezelfde repository. Als je met iemand samenwerkt aan een feature en je hebt beiden schrijfrechten op het project, kan je een topic branch pushen naar de repository en een Pull Request openen naar de master-branch van hetzelfde project om het code review en discussie proces te starten. Forken is niet noodzakelijk.

Pull Requests voor gevorderden

Nu we de grondbeginselen van bijdragen aan een project op GitHub hebben behandeld, laten we een paar interessante tips en truks zien met betrekking tot Pull Requests zodat je nog effectiever kunt zijn in het gebruik.

Pull Requests als patches

Het is belangrijk om te begrijpen dat veel projecten Pull Requests niet echt zien als stapels met perfecte patches die altijd netjes achterelkaar zullen kunnen worden toegepast, zoals de meeste maillijst-gebaseerde projecten de reeks bijgedragen patches zien. De meeste GitHub projecten zien Pull Request branches als iteratieve conversaties rond een voorgestelde wijziging, uitmondend in een unified diff die met een merge wordt toegepast.

Dit is een belangrijk onderscheid, omdat de wijziging over het algemeen wordt voorgesteld voordat de code als perfect wordt beschouwd, wat zeldzamer is bij de reeks patch bijdragen in maillijsten. Dit maakt een vroeg gesprek mogelijk met de beheerders zodat het vinden van een goede oplossing meer een inspanning wordt van de hele gemeenschap. Als code wordt voorgesteld met een Pull Request en de beheerders of de gemeenschap een wijziging voorstellen wordt de reeks patches niet opnieuw samengesteld, maar daarentegen wordt het verschil gepusht als een nieuwe commit op de branch, waarbij de conversatie doorgaat met behoud van de context van het vorige werk.

Bijvoorbeeld, als je Pull Request finaal erop terugslaat, zal je zien dat de bijdrager zijn commit niet heeft gerebased en een andere Pull Request heeft gestuurd. In plaats daarvan zijn er nieuwe commits toegevoegd en deze zijn naar de bestaande branch gepusht. Op deze manier kan je in de toekomst teruggaan naar deze Pull Request en alle context terugvinden waarop besluiten zijn genomen. De “Merge” knop indrukken op de site maakt opzettelijk een merge commit die aan de Pull Request refereert zodat het eenvoudig is om terug te gaan en de oorspronkelijke conversatie te onderzoeken mocht het nodig zijn.

Met de upstream bijblijven

Als je Pull Request veroudert raakt of om een andere reden niet schoon merget, zal het willen corrigeren zodat de onderhouder deze eenvoudig kan mergen. GitHub zal dit voor je controleren en je aan de onderkant van elke Pull Request laten weten of de merge triviaal is of niet.

PR merge faalt
Figuur 97. Pull Request zal niet netjes mergen

Als je zoiets als Pull Request zal niet netjes mergen ziet, zal je jouw branch willen repareren zodat het groen wordt en de onderhouder geen extra werk heoft te doen.

Je hebt twee voor de hand liggende opties om dit te doen. Je kunt je branch rebasen op waar de target branch is (normaalgesproken de master-branch van de repository die je hebt geforked), of je kunt de target branch in je eigen branch mergen.

De meeste ontwikkelaars op GitHub zullen het laatste doen, om dezelfde redenen die we behandeld hebben in de vorige paragraaf. Waar het om draait is de historie en de laatste merge, dus rebasen geeft je niet veel meer dan een enigzins schonere historie en is aan de andere kant veel moeilijker en foutgevoeliger.

Als je de target branch wilt mergen om je Pull Request merge-baar te maken, moet je de oorspronkelijke repository als een nieuwe remote moeten toevoegen, ervan fetchen, de hoofdbranch van die repository in jouw topic branch mergen, de problemen oplossen als ze er zijn en daarna je topic branch weer terugpushen naar dezelfde branch als waar je de Pull Request op geopend hebt.

Als voorbeeld, stel dat in het “tonychacon” voorbeeld dat we hiervoor gebruikt hebben, de oorspronkelijke auteur een wijziging gemaakt heeft die een conflict in het Pull Request veroorzaakt. Laten we de stappen eens doorlopen.

$ git remote add upstream https://github.com/schacon/blink (1)

$ git fetch upstream (2)
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (3/3), done.
Unpacking objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
From https://github.com/schacon/blink
 * [new branch]      master     -> upstream/master

$ git merge upstream/master (3)
Auto-merging blink.ino
CONFLICT (content): Merge conflict in blink.ino
Automatic merge failed; fix conflicts and then commit the result.

$ vim blink.ino (4)
$ git add blink.ino
$ git commit
[slow-blink 3c8d735] Merge remote-tracking branch 'upstream/master' \
    into slower-blink

$ git push origin slow-blink (5)
Counting objects: 6, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 682 bytes | 0 bytes/s, done.
Total 6 (delta 2), reused 0 (delta 0)
To https://github.com/tonychacon/blink
   ef4725c..3c8d735  slower-blink -> slow-blink
  1. Voeg de oorspronkelijke repository als remote toe met de naam “upstream”

  2. Fetch het nieuwste werk van die remote

  3. Merge de main branch in jouw topic branch

  4. Los het conflict op dat optrad

  5. Push naar dezelfde topic branch

Als je dat gedaan hebt zal de Pull Request automatisch geupdate worden en opnieuw gecontroleerd of het zuiver merget.

PR gerepareerd
Figuur 98. Pull Request merget goed

Een van de geweldige dingen aan Git is dat je dat constant kunt blijven doen. Als je een erg lang-lopend project hebt, kan je eenvoudig keer op keer de target branch mergen en hoef je alleen de conflicten op te lossen die zijn opgetreden sinds de laatste keer dat je gemerged hebt, wat het proces erg beheerbaar maakt.

Als je perse de branch wilt rebasen om het op te schonen, kan je dat zeker doen, maar het wordt je sterk aangeraden om niet te force pushen naar de branch waar al een Pull Request op is geopend. Als andere mensen deze hebben gepulld en er op zijn gaan doorwerken, krijg je te maken met alle problemen die zijn genoemd in De gevaren van rebasen. In plaats daarvan push je de gerebasede branch naar een nieuwe branch op GitHub en open je een gloednieuwe Pull Request waarin je aan de oude refereert, en sluit daarna het orginele request.

Referenties

Je volgende vraag zou “Hoe refereer ik aan het oude Pull Request?” kunnen zijn. Er blijken vele, vele manieren te zijn waarop je aan andere dingen kunt refereren zo ongeveer overaal waar je kunt schrijven in GitHub.

Laten we beginnen met hoe naar een andere Pull Request of Issue te verwijzen. Alle Pull Requests en Issues hebben een nummer toegewezen gekregen en deze zijn uniek binnen het project. Bijvoorbeeld, je kunt geen Pull Request #3 en Issue #3 hebben. Als je aan enig Pull Request of Issue wilt refereren vanuit een andere, kan je eenvoudigweg #<num> in elke commentaar of omschrijving neerzetten. Je kunt specifieker zijn als het Issue of Pull Request elders leeft; schrijf gebruikersnaam#<num> als je aan een Issue of Pull Request refereert in een fork of repository waar je in zit, of gebruikersnaam/repo#<num> om te refereren aan iets in een andere repository.

Laten we naar een voorbeeld kijken. Stel we hebben de branch in het vorige voorbeeld gerebased, een nieuwe pull request ervoor gemaakt en nu willen we verwijzen naar de oude pull request vanuit de nieuwe. We willen ook refereren naar een issue in de fork van de repository in een heel ander project. We maken de beschrijving als in Verwijzingen in een Pull Request..

PR verwijzingen
Figuur 99. Verwijzingen in een Pull Request.

Als we deze pull request indienen, zien we dit alles getoond als Verwijzingen getoond in een Pull Request..

PR verwijzingen getoond
Figuur 100. Verwijzingen getoond in een Pull Request.

Merk op dat de volledige GitHub URL die we erin gezet hebben afgekort is tot alleen de benodigde informatie.

Als Tony nu het orginele Pull Request gaat sluiten, zien we dit doordat we het vermelden in de nieuwe, GitHub heeft automatisch een terugslag gebeurtenis aangemaakt in de tijdslijn van het Pull Request. Dit betekent dat iedereen die dit Pull Request bezoekt en ziet dat het is gesloten eenvoudig kan teruglinken naar degene die het overschrijft. De link zal eruit zien als Verwijzing getoond in een Pull Request..

PR gesloten
Figuur 101. Verwijzing getoond in een Pull Request.

Naast issue nummers, kan je ook refereren aan een specifieke commit door middel van de SHA-1. Je moet een volledige 40 positie SHA-1 vermelden, maar als GitHub dat in een commentaar ziet, zal het direct linken naar de commit. Nogmaals, je kunt aan commits refereren in forks of andere repositories op dezelfde manier als je deed met issues.

Markdown met een GitHub smaakje

Linken naar andere Issues is maar het begin van de interessante dingen die je met bijna elke tekstbox op GitHub kan doen. In Issue en Pull Request omschrijvingen, commentaren, code commentaren en andere zaken kan je de zogenoemde “GitHub Flavored Markdown” (Markdown met een GitHub smaakje) gebruiken. Markdown is als schrijven in platte tekst maar wat met meer functionaliteit wordt getoond.

Zie Een voorbeeld van Markdown zoals geschreven en getoond. voor een voorbeeld van hoe comemntaar of tekst kan worden geschreven en daarna getoond met Markdown.

Voorbeeld Markdown
Figuur 102. Een voorbeeld van Markdown zoals geschreven en getoond.

Het smaakje wat GitHub aan Markdown meegeeft is meer dan wat je met de standaard Markdown krijgt. Deze smaakjes kunnen alle heel nuttig zijn als je bruikbare Pull Requests of Issue commentaar of omschrijvingen maakt.

Taaklijsten

Het eerste echt bruikbare GitHub specifieke Markdown optie, vooral in het gebruik in Pull Requests, is de taaklijst. Een taaklijst is een lijst van checkboxen met dingen die je gedaan wilt hebben. Het neerzetten ervan in een Issue of Pull Request geeft normaalgesproken de dingen weer die je gedaan wilt hebben voordat je het onderwerp voor gesloten beschouwt.

Je kunt op deze manier een taaklijst maken:

- [X] Write the code
- [ ] Write all the tests
- [ ] Document the code

Als we deze in de omschrijving van een Pull Request of Issue zetten, zullen we het als Taaklijsten zoals getoond een Markdown commentaar. getoond zien

voorbeel taaklijst
Figuur 103. Taaklijsten zoals getoond een Markdown commentaar.

Dit wordt vaak in een Pull Request gebruikt om aan te geven wat je allemaal gedaan wilt zien op de branch voordat de Pull Request klaar is om te mergen. Het echte gave hiervan is dat je eenvoudig op de checkboxen kunt klikken om het commentaar bij te werken — je hoeft de tekst van de Markdown zelf niet te wijzigen om de taken af te tikken.

En er is meer: GitHub zal naar taaklijsten zoeken in je Issues en Pull Requesten en deze als metadata op de pagina tonen die ze bevatten. Bijvoorbeeld, als je een Pull Request hebt met taken en je kijkt naar de overzichtspagina van alle Pull Requesten, kan je zien in hoeverre het klaar is. Dit helpt mensen om Pull Requests in te delen naar subtaken en andere mensen om de voortgang van de branch te volgen. Je kunt een voorbeeld hiervan zien in Samenvatting van taaklijsten in de Pull Request lijst..

Voorbeeld taaklijst
Figuur 104. Samenvatting van taaklijsten in de Pull Request lijst.

Dit is ontzettend handig als je vroeg een Pull Request opent en deze gebruikt om de voortgang te volgen tijdens de implementatie van de feature.

Code Snippets (code knipsels)

Je kun ook code knipsels aan commentaren toevoegen. Dit is in het bijzonder handig als je iets wilt voorstellen wat je zou kunnen proberen te doen voordat je het daadwerkelijk implementeert als een commit in je branch. Dit wordt ook vaak gebruikt om een voorbeeld te geven de code die niet werkt of wat in deze Pull Request zou kunnen worden geïmplementeerd.

Om een code knipsel toe te voegen moet je het met backticks omsluiten.

```java
for(int i=0 ; i < 5 ; i++)
{
   System.out.println("i is : " + i);
}
```

Als je de naam van de taal toevoegt, zoals we hier met java gedaan hebben, zal GitHub proberen ook de syntax te markeren. In het bovenstaande voorbeeld zou het worden getoond als Getoonde omsloten code voorbeeld..

Getoonde omsloten code
Figuur 105. Getoonde omsloten code voorbeeld.

Quoting (Citeren)

Als je reageert op een klein deel van een lang commentaar, kan je naar keuze citeren uit het andere commentaar door de regel te laten beginen met het > teken. Dit is zelfs zo gewoon en bruikbaar dat er een sneltoets combinatie voor gemaakt is. Als je de tekst selecteert in het commentaar waar je direct op wilt reageren en de r toets indrukt, wordt deze direct voor je als citaat in de commentaar ruimte geplaatst.

De citaten zien er zo ongeveer uit:

> Whether 'tis Nobler in the mind to suffer
> The Slings and Arrows of outrageous Fortune,

How big are these slings and in particular, these arrows?

Zodra getoond, zal het commentaar er als Getoond citaat voorbeeld. uitzien.

Getoonde citaat
Figuur 106. Getoond citaat voorbeeld.

Emoji

Als laatste, kan je ook emoji in je commentaar gebruiken. Dit wordt eigenlijk best wel vaak gebruikt in de commentaren die je bij veel GitHub issues en Pull Requests ziet. Er is zelfs een emoji hulp in GitHub. Als je een commentaar intypt en je begint met een : teken, zal een automatische voltooihulp je komen helpen met vinden wat je zoekt.

Emoji voltooi hulp
Figuur 107. Emoji voltooi hulp in actie.

Emojis komen er als :<naam>: uit te zien ergens in je commentaar. Je zou bijvoorbeeld iets als dit kunnen schrijven:

I :eyes: that :bug: and I :cold_sweat:.

:trophy: for :microscope: it.

:+1: and :sparkles: on this :ship:, it's :fire::poop:!

:clap::tada::panda_face:

Als het wordt getoond, komt het er als Zwaar emoji commentaar. uit te zien.

Emoji
Figuur 108. Zwaar emoji commentaar.

Niet dat het erg veel inhoudelijk toevoegt, maar het geeft wel wat sjeu en emotie aan een medium dat normaalgesproken nogal moeilijk emoties laat weergeven.

Noot

Er zijn vandaag de dag nogal wat webservices die gebruik maken van emoji. Een goede spiekbrief voor het vinden van emoji die uitdrukken wat je wilt zeggen kan je vinden op:

Plaatjes

Technisch gezien is het geen GitHub smaak van Markdown, maar het is erg handig. Naast het toevoegen van Markdown plaatjes links aan commentaar, waarvan het moeilijk kan zijn om URLs voor te vinden en in te voegen, staat GitHub je toe om plaatjes te slepen en lossen (drag & drop) in tekstgebieden om ze in te voegen.

Plaatjes slepen en lossen
Figuur 109. Slepen en lossen van plaatjes om ze te uploaden en automatisch in te voegen.

Als je terugkijkt naar Verwijzingen in een Pull Request., kan je een kleine “Parsed as Markdown” hint boven het tekstgebied zien. Als je hierop klikt zal dit je een complete spiekbrief laten zien van alles wat met met Markdown in GitHub kunt doen.

Houd je GitHub openbare repository up-to-date

Als je eenmaal een GitHub repository geforkt hebt, bestaat jouw repository (jouw "fork") onafhankelijk van het orgineel. In het bijzonder, als de originele repository nieuwe commits heeft, informeert GitHub je met een bericht als deze:

This branch is 5 commits behind progit:master.

Maar houw GitHub repository zal nooit automatisch worden bijgewerkt door GitHub; dit is iets wat je zelf moet doen. Gelukkig is dit erg eenvoudig te doen.

Een mogelijkheid om dit te doen vereist geen configuratie. Bijvoorbeeld, als je van https://github.com/progit/progit2.git geforkt hebt, kan je als volgt jouw master branch up-to-date houden:

$ git checkout master (1)
$ git pull https://github.com/progit/progit2.git (2)
$ git push origin master (3)
  1. Als je op een andere branch zit, keer terug naar master.

  2. Fetch wijzigingen van https://github.com/progit/progit2.git en merge ze in master.

  3. Push jouw master branch naar origin.

Dit werkt, maar het is een beetje saai om elke keer de fetch URL helemaal te moeten typen. Je kuknt dit met een beetje configuratie automatiseren.

$ git remote add progit https://github.com/progit/progit2.git (1)
$ git branch --set-upstream-to=progit/master master (2)
$ git config --local remote.pushDefault origin (3)
  1. Voeg de bron repository toe en geef het een naam. Hier heb ik de naam progit gekozen

  2. Stel je master branch in om te fetchen van de progit remote.

  3. Zorg ervoor dat de standaard push repository origin is.

Als dit eenmaal gedaan is, wordt de workflow veel simpeler:

$ git checkout master (1)
$ git pull (2)
$ git push (3)
  1. Als je op een andere branch zit, keer terug naar master.

  2. Fetch wijzigingen van progit en merge ze in master.

  3. Push jouw master branch naar origin.

Deze aanpak kan handig zijn, maar het is niet zonder nadelen. Git zal vrolijk al dit werk stilletjes voor je doen, maar het zal je niet waarschuwen als je een commit naar master doet, van progit pullt en dan naar origin pusht; al deze handelingen zijn geldig met deze opzet. Dus je moet goed opletten om nooit direct naar master te committen, omdat die branch effectief een voorliggende repository toebehoort.

scroll-to-top