6.2 GitHub - Bidra till ett projekt

Tony letar efter kod att köra på sin programmerbara Arduino-mikrostyrning och har hittat en bra programfil på GitHub på https://github.com/schacon/blink.

Det enda problemet är att blinktakten är för hög. Vi tycker att det är trevligare att vänta 3 sekunder i stället för 1 mellan varje lägesändring. Låt oss förbättra programmet och skicka tillbaka det till projektet som en föreslagen ändring.

Först klickar vi på knappen för att avgrena som nämndes tidigare för att få en egen kopia av projektet. Vårt användarnamn här är "tonychacon", så vår kopia av projektet finns på https://github.com/tonychacon/blink och det är där vi kan redigera den. Vi klonar den lokalt, skapar en ämnesgren, gör kodändringen och skickar slutligen upp ändringen tillbaka till GitHub.

Om vi nu går tillbaka till vår avgrening på GitHub kan vi se att GitHub har märkt att vi har skickat upp en ny ämnesgren och presenterar en stor grön knapp för att granska våra ändringar och öppna en ändringsförfrågan mot ursprungsprojektet.

Du kan också gå till sidan för grenar på https://github.com/<user>/<project>/branches för att hitta din gren och öppna en ny ändringsförfrågan därifrån.

Om vi klickar på den gröna knappen får vi en skärm som ber oss ange titel och beskrivning för ändringsförfrågan. Det är nästan alltid värt att lägga lite tid på detta, eftersom en bra beskrivning hjälper ägaren av ursprungsprojektet att avgöra vad du försökte göra, om de föreslagna ändringarna är riktiga och om det förbättrar projektet att ta in dem.

Vi ser också en lista över incheckningarna i vår ämnesgren som ligger före master-grenen (i det här fallet bara en) samt en sammanfogad diff över alla ändringar som görs om grenen sammanfogas av projektägaren.

När du trycker på knappen för att skapa ändringsförfrågan på den här skärmen får ägaren av projektet du avgrenade en avisering om att någon föreslår en ändring, och en länk till en sida som innehåller all informationen.

Här kan projektägaren granska den föreslagna ändringen och sammanfoga den, avvisa den eller kommentera den. Säg att han gillar idén, men föredrar att lampan är släckt lite längre än den är tänd.

I arbetsflödena i Distribuerat Git kan sådana samtal ske via e-post; på GitHub sker det på webben. Projektägaren kan granska den sammanfogade diffen och lämna en kommentar genom att klicka på någon av raderna.

När förvaltaren gör denna kommentar får den som öppnade ändringsförfrågan (och i själva verket alla som följer kodförrådet) en avisering. Vi går igenom hur du anpassar det senare, men om han hade e-postaviseringar aktiverade skulle Tony få ett e-postmeddelande som detta:

Vem som helst kan också lämna allmänna kommentarer på ändringsförfrågan. I Diskussionssida för ändringsförfrågan ser vi ett exempel där projektägaren både kommenterar en kodrad och sedan lämnar en allmän kommentar i diskussionsdelen. Du ser att kodkommentarerna förs in i samtalet.

Nu kan bidragslämnaren se vad som behöver göras för att få ändringen godkänd. Lyckligtvis är det mycket rakt på sak. Där man via e-post kan behöva rulla om sin serie och skicka in den till e-postlistan igen, räcker det på GitHub att checka in i ämnesgrenen igen och skicka, vilket automatiskt uppdaterar ändringsförfrågan. I Ändringsförfrågan, slutligt läge kan du också se att den gamla kodkommentaren har fällts ihop i den uppdaterade ändringsförfrågan, eftersom den gjordes på en rad som sedan ändrats.

Att lägga till incheckningar i en befintlig ändringsförfrågan triggar ingen avisering, så när Tony har skickat upp sina rättelser väljer han att lämna en kommentar för att meddela projektägaren att han gjort den begärda ändringen.

En intressant detalj är att om du klickar på fliken för ändrade filer i ändringsförfrågan får du den sammanfogade diffen — alltså den sammanlagda skillnaden som skulle införas i din huvudgren om ämnesgrenen sammanfogas. I git diff-termer visar den i praktiken automatiskt git diff master…​<branch> för grenen som ändringsförfrågan bygger på. Se Avgöra vad som ska integreras för mer om denna typ av diff.

Det andra du märker är att GitHub kontrollerar om ändringsförfrågan sammanfogas rent och erbjuder en knapp för att göra sammanslagningen åt dig på servern. Den knappen visas bara om du har skrivrättigheter till kodförrådet och en enkel sammanslagning är möjlig. Om du klickar på den utför GitHub en icke-snabbspolad sammanslagning, vilket betyder att även om sammanslagningen skulle kunna snabbspolas, skapar den ändå en sammanslagningsincheckning.

Om du föredrar kan du helt enkelt dra ner grenen och sammanfoga den lokalt. Om du sammanfogar grenen in i master-grenen och skickar upp den till GitHub stängs ändringsförfrågan automatiskt.

Det här är det grundläggande arbetsflödet som de flesta GitHub-projekt använder. Ämnesgrenar skapas, ändringsförfrågningar öppnas, en diskussion följer, eventuellt görs mer arbete i grenen och till sist stängs eller sammanfogas förfrågan.

Det är viktigt att förstå att många projekt inte riktigt ser ändringsförfrågningar som köer av perfekta ändringspatchar som ska appliceras rent i ordning, såsom de flesta e-postlistebaserade projekt ser bidrag i form av ändringspatchserier. De flesta GitHub-projekt ser ämnesgrenar för ändringsförfrågningar som iterativa samtal kring en föreslagen ändring, som mynnar ut i en sammanfogad diff som appliceras genom sammanslagning.

Det här är en viktig skillnad, eftersom ändringar ofta föreslås innan koden är helt färdig, vilket är betydligt ovanligare i e-postlistebaserade patchserier. Det möjliggör ett tidigare samtal med förvaltarna så att rätt lösning blir mer av ett gemensamt arbete. När kod föreslås via en ändringsförfrågan och förvaltare eller gemenskapen föreslår en ändring, rullas ändringspatchserien i regel inte om, utan skillnaden skickas upp som en ny incheckning till grenen, vilket för samtalet framåt med tidigare kontext intakt.

Om du till exempel går tillbaka och tittar på Ändringsförfrågan, slutligt läge ser du att bidragslämnaren inte ombaserade sin incheckning och skickade in en ny ändringsförfrågan. I stället lade de till nya incheckningar och skickade upp dem till den befintliga grenen. På så vis kan du gå tillbaka och se all kontext kring varför beslut fattades. När du trycker på sammanslagningsknappen på webbplatsen skapas medvetet en sammanslagningsincheckning som refererar till ändringsförfrågan så att det är lätt att gå tillbaka och undersöka den ursprungliga diskussionen vid behov.

Om din ändringsförfrågan blir inaktuell eller på annat sätt inte går att sammanfoga rent vill du åtgärda den så att förvaltaren enkelt kan sammanfoga. GitHub kontrollerar detta åt dig och talar om längst ner i varje ändringsförfrågan om sammanslagningen är enkel eller inte.

Om du ser något som Ändringsförfrågan sammanfogas inte rent vill du fixa din gren så att den blir grön och förvaltaren slipper extra arbete.

Du har två huvudalternativ för att göra det. Antingen ombaserar du din gren ovanpå den gren som är målet (vanligen master i kodförrådet du avgrenade), eller så sammanfogar du målets gren in i din egen gren.

De flesta utvecklare på GitHub väljer det senare, av samma skäl som vi gick igenom i föregående avsnitt. Det som spelar roll är historiken och den slutliga sammanslagningen, så ombasering ger dig inte mycket mer än en lite renare historik och är i gengäld betydligt svårare och mer felbenägen.

Om du vill sammanfoga målgrenen för att göra ändringsförfrågan sammanslagningsbar lägger du till ursprungskodförrådet som ett nytt fjärrkodförråd, uppdaterar därifrån, sammanfogar huvudgrenen från det kodförrådet in i din ämnesgren, löser eventuella problem och skickar sedan upp tillbaka till samma gren som ändringsförfrågan pekar på.

Till exempel, säg att vi i "tonychacon"-exemplet från tidigare använder, gjorde ursprungsförfattaren en ändring som skapade en konflikt i ändringsförfrågan. Låt oss gå igenom stegen.

När du har gjort detta uppdateras ändringsförfrågan automatiskt och kontrolleras igen för att se om den sammanfogas rent.

En av de stora fördelarna med Git är att du kan göra detta kontinuerligt. Om du har ett projekt som pågår länge kan du enkelt sammanfoga från målgrenen om och om igen och bara behöva hantera konflikter som uppstått sedan senaste sammanslagningen, vilket gör processen lätt att hantera.

Om du absolut vill ombasera grenen för att städa till den kan du göra det, men det är starkt rekommenderat att inte tvinga upp en ombaserad gren över den gren som ändringsförfrågan redan pekar på. Om andra har dragit ner den och gjort mer arbete stöter du på problemen som beskrivs i Farorna med grenflyttning. Skicka i stället upp den ombaserade grenen till en ny gren på GitHub och öppna en helt ny ändringsförfrågan som refererar till den gamla, och stäng sedan den ursprungliga.

Din nästa fråga kan vara "Hur refererar jag den gamla ändringsförfrågan?". Det visar sig att det finns många sätt att referera till andra saker nästan överallt där du kan skriva i GitHub.

Vi börjar med hur du korsrefererar en annan ändringsförfrågan eller ett ärende. Alla ändringsförfrågningar och ärenden får nummer och de är unika inom projektet. Du kan till exempel inte ha ändringsförfrågan #3 och ärende #3. Om du vill referera till en ändringsförfrågan eller ett ärende från en annan kan du helt enkelt skriva #<num> i en kommentar eller beskrivning. Du kan också vara mer specifik om ärendet eller ändringsförfrågan ligger någon annanstans: skriv användare#<num> om du refererar till ett ärende eller en ändringsförfrågan i en avgrening av kodförrådet du är i, eller användare/kodförråd#<num> för att referera till något i ett annat kodförråd.

Låt oss titta på ett exempel. Säg att vi ombaserade grenen i det föregående exemplet, skapade en ny ändringsförfrågan för den, och nu vill vi referera till den gamla ändringsförfrågan från den nya. Vi vill också referera till ett ärende i avgreningen av kodförrådet och ett ärende i ett helt annat projekt. Vi kan fylla i beskrivningen som i Korsreferenser i en ändringsförfrågan.

När vi skickar in ändringsförfrågan ser vi allt renderat som i Korsreferenser renderade i en ändringsförfrågan.

Lägg märke till att hela GitHub-adressen vi la in kortades till precis den information som behövs.

När Tony går tillbaka och stänger den ursprungliga ändringsförfrågan ser vi att GitHub automatiskt har skapat en återkopplingshändelse i ändringsförfrågans tidslinje, eftersom vi nämnde den i den nya. Det betyder att den som besöker ändringsförfrågan och ser att den är stängd enkelt kan länka tillbaka till den som ersatte den. Länken ser ut ungefär som i Länk tillbaka till den nya ändringsförfrågan i tidslinjen för den stängda.

Utöver ärendenummer kan du även referera till en specifik incheckning via SHA-1. Du måste ange hela SHA-1 på 40 tecken, men om GitHub ser det i en kommentar länkar den direkt till incheckningen. Återigen kan du referera till incheckningar i avgreningar eller andra kodförråd på samma sätt som med ärenden.

Den första riktigt användbara GitHub-specifika Markdown-funktionen, särskilt i ändringsförfrågningar, är uppgiftslistan. En uppgiftslista är en lista med kryssrutor för saker du vill få gjort. Att lägga dem i ett ärende eller en ändringsförfrågan innebär normalt sådant du vill ha gjort innan du anser att saken är klar.

Du kan skapa en uppgiftslista så här:

Om vi tar med detta i beskrivningen av vår ändringsförfrågan eller vårt ärende ser det renderat ut som i Uppgiftslistor renderade i en Markdown-kommentar.

Detta används ofta i ändringsförfrågningar för att ange vad du vill få gjort i grenen innan ändringsförfrågan är redo att sammanfogas. Det riktigt smidiga är att du kan klicka i kryssrutorna för att uppdatera kommentaren — du behöver inte redigera Markdownen direkt för att bocka av uppgifter.

Dessutom letar GitHub efter uppgiftslistor i dina ärenden och ändringsförfrågningar och visar dem som metadata på sidorna som listar dem. Om du till exempel har en ändringsförfrågan med uppgifter och du tittar på översiktssidan med alla ändringsförfrågningar ser du hur långt den kommit. Det hjälper människor att bryta ned ändringsförfrågningar i deluppgifter och hjälper andra att följa grenens framsteg. Du kan se ett exempel i Sammanfattning av uppgiftslista i ändringsförfrågelistan.

Det är oerhört användbart när du öppnar en ändringsförfrågan tidigt och använder den för att spåra framstegen i implementationen av en funktion.

Du kan också lägga till kodsnuttar i kommentarer. Det är särskilt användbart om du vill visa en möjlig lösning innan du checkar in den i din gren. Det används också ofta för att lägga in exempelkod som visar vad som inte fungerar eller hur ändringsförfrågan kan lösas.

För att lägga till en kodsnutt måste du "stängsla in" den med omvända citattecken.

Om du lägger till ett språknamn som vi gjorde med "java" kommer GitHub också att försöka syntaxmarkera snutten. I fallet ovan skulle den renderas ungefär som i Renderat exempel på inhägnad kod.

Om du svarar på en liten del av en lång kommentar kan du citera delar av den andra kommentaren genom att inleda raderna med tecknet >. Faktum är att detta är så vanligt och användbart att det finns en kortkommando för det. Om du markerar text i en kommentar du vill svara direkt på och trycker r får du texten citerad i kommentarsrutan.

Citaten ser ut ungefär så här:

När kommentaren renderas ser den ut som i Renderat exempel på citat.

Till sist kan du också använda emoji i dina kommentarer. Det används rätt flitigt i kommentarer i många GitHub-ärenden och ändringsförfrågningar. Det finns till och med en emoji-hjälpare i GitHub. Om du skriver en kommentar och börjar med tecknet : hjälper en autokomplettering dig att hitta det du söker.

Emoji skrivs som :<namn>: var som helst i kommentaren. Till exempel kan du skriva något i stil med detta:

När det renderas ser det ut ungefär som i Mycket emoji i kommentarer.

Det är inte särskilt nyttigt, men det ger ett inslag av lek och känsla i ett medium där det annars är svårt att förmedla känslor.

Det här är inte tekniskt sett GitHub-anpassad Markdown, men det är otroligt användbart. Utöver att lägga till Markdown-bildlänkar i kommentarer, vilket kan vara svårt att hitta och bädda in URL:er för, låter GitHub dig dra och släppa bilder i textrutor för att bädda in dem.

Om du tittar på Dra och släpp bilder för att ladda upp och bädda in automatiskt ser du en liten text "Tolkad som Markdown" ovanför textrutan. Om du klickar på den får du ett fullständigt fuskblad över allt du kan göra med Markdown på GitHub.