6.2 GitHub - Aan een project bijdragen

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 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.

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.

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.

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.

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.

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:

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.

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.

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.

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.

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.

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.

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

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.

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..

Als we deze pull request indienen, zien we dit alles getoond als 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..

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.

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:

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

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..

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.

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.

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..

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:

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

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.

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

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

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.

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.

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.