Chapters ▾ 2nd Edition

6.2 GitHub - Bydra tot 'n projek

Bydra tot 'n projek

Noudat die rekening opgestel is, kom ons loop deur die besonderhede wat jou kan help om by te dra tot bestaande projekte.

Projekte afsplits (forking [forking])

As jy wil bydra tot 'n bestaande projek waarby jy nie push-toegang [push access] het nie, kan jy die projek ``fork''. Dit hou in dat GitHub jou 'n kopie van die projek laat maak wat heeltemal joune is; dit bestaan in die naamruimte [namespace] van jou gebruiker en jy kan daarheen push.

Note

Histories gesien is die term fork'' 'n bietjie negatief in konteks, in die sin dat iemand 'n oopbron-projek [open source project] in 'n ander rigting gelei het, soms 'n mededingende projek geskep het en die bydraers onderling verdeel het. Op GitHub is 'n fork'' bloot dieselfde projek in jou naamruimte, wat jou toelaat om veranderinge aan 'n projek openbaar te maak met die doel om op 'n meer oop manier by te dra.

Op hierdie manier hoef projekte nie bekommerd te wees om gebruikers as bydraers by te voeg om hulle push-toegang te gee nie. Mense kan 'n projek fork, daarheen push, en hulle veranderinge terugbring na die oorspronklike projek deur 'n sogenaamde Pull Request te skep, wat ons binnekort sal behandel. Dit open 'n gespreksdraad [discussion thread] met kodenagaan [code review], en die eienaar en die bydraer kan dan oor die verandering kommunikeer totdat die eienaar tevrede is, waarna die eienaar dit kan merge.

Om 'n projek te fork, besoek jy die projekbladsy en klik op die ``Fork''-knoppie regs bo op die bladsy.

Die ``Fork''-knoppie.
Figure 101. Die ``Fork''-knoppie.

Na 'n paar sekondes sal jy na jou nuwe projekbladsy gelei word, met jou eie skryfbare kopie van die kode.

Die GitHub-vloei (flow [flow])

GitHub is ontwerp rondom 'n spesifieke samewerkings-werksvloei [collaboration workflow] wat om pull requests draai. Hierdie werksvloei werk of jy nou saamwerk met 'n hegte span in 'n enkele gedeelde bewaarplek [repository], of 'n maatskappy wat wêreldwyd versprei is, of 'n netwerk van vreemdelinge wat bydra tot 'n projek deur middel van baie forks. Dit is gerig op die Onderwerp-takke (Topic Branches)-werksvloei wat behandel is in Git Branching.

Hier is hoe dit oor die algemeen werk:

  1. Fork die projek

  2. Maak 'n onderwerptak [topic branch] van master.

  3. Doen 'n aantal commits om die projek te verbeter.

  4. Push hierdie tak [branch] na jou GitHub-projek.

  5. Open 'n Pull Request op GitHub.

  6. Bespreek en bly commit soos jy wil.

  7. Die projekeienaar merge of sluit die Pull Request.

  8. Sinkroniseer die opgedateerde master terug na jou fork

Dit is eintlik die Integrasiebestuurder-werksvloei [Integration Manager workflow] soos dit behandel is in [_integration_manager], maar in plaas daarvan om e-pos te gebruik om te kommunikeer en veranderinge na te gaan, gebruik spanne die web-gebaseerde instrumente van GitHub.

Kom ons bespreek 'n voorbeeld van 'n voorstel tot verandering aan 'n oopbron-projek wat op GitHub gehuisves word en wat hierdie werksvloei gebruik.

'n Pull Request skep

Tony is op soek na kode om op sy Arduino programmeerbare mikrobeheerder [microcontroller] te laat loop en het 'n fantastiese projek op GitHub gevind by https://github.com/schacon/blink.

Die projek waartoe ons wil bydra.
Figure 102. Die projek waartoe ons wil bydra.

Die enigste probleem is dat die lig te vinnig flikker. Ons voel dit is baie beter as ons 3 sekondes wag in plaas van 1 tussen elke statusverandering. Kom ons verbeter dus die program en stuur dit terug na die projek as 'n veranderingsvoorstel.

Eerstens klik ons die 'Fork'-knoppie soos vantevore genoem om ons eie kopie van die projek te kry. Ons gebruikersnaam is in hierdie geval `tonychacon'', dus ons kopie van hierdie projek is by `https://github.com/tonychacon/blink en dit is waar ons dit kan verander. Ons kloon [clone] dit plaaslik, maak 'n onderwerptak, doen die kodeverandering en druk ten slotte die verandering weer na 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 ons fork van die projek plaaslik

  2. Maak 'n beskrywende onderwerptak

  3. Voer ons verandering aan die kode uit

  4. Kontroleer dat die verandering korrek is

  5. Commit die verandering na die onderwerptak

  6. Push ons nuwe onderwerptak terug na ons GitHub-fork

As ons nou teruggaan na ons fork op GitHub, kan ons sien dat GitHub opgemerk het dat ons 'n nuwe onderwerptak gepush het, en dit wys vir ons 'n groot groen knoppie om ons veranderinge te bekyk en 'n Pull Request na die oorspronklike projek oop te maak.

'n Alternatief sou wees om na die `Branches''-bladsy te gaan by `https://github.com/<user>/<project>/branches, jou tak op te soek en 'n Pull Request vanaf daardie plek oop te maak.

Pull Request-knoppie
Figure 103. Pull Request-knoppie

As ons op daardie groen knoppie klik, sal ons 'n skerm sien wat ons in staat stel om 'n titel en 'n beskrywing vir die verandering wat ons wil aanvra, in te voer. Dit is oor die algemeen 'n goeie idee om moeite te doen om die beste moontlike beskrywing te skryf, sodat die eienaar van die oorspronklike projek weet waarom dit voorgestel word, dat jou verandering korrek is, en waarom dit 'n waardevolle verandering is indien dit aanvaar word.

Ons sien ook 'n lys van die commits in ons onderwerptak wat `voorloop'' op die `master-tak (in hierdie geval, net hierdie een), en 'n eenvormige verskil [unified diff] van al die veranderinge wat gemaak sal word as hierdie tak deur die projekeienaar gemerge sou word.

Pull Request-skepping
Figure 104. Pull Request-skeppingsbladsy

As jy op die 'Create pull request'-knoppie op hierdie bladsy druk, sal die eienaar van die projek waarvandaan jy geforkit het 'n boodskap kry dat iemand 'n verandering voorstel, en dit sal wys na 'n bladsy waar al hierdie inligting vermeld word.

Note

Alhoewel Pull Requests gewoonlik gebruik word vir openbare projekte soos hierdie een, waar die bydraer 'n volledige verandering gereed het, word dit ook dikwels in interne projekte gebruik aan die begin van die ontwikkelsiklus. Aangesien jy kan bly push na die onderwerptak selfs nadat die Pull Request oopgemaak is, word dit dikwels vroeg oopgemaak en gebruik as 'n manier om aan werk te itereer as 'n span binne 'n konteks, in plaas daarvan om heeltemal aan die einde van die proses oopgemaak te word.

Iterasies op 'n Pull Request

Op hierdie punt kan die projekeienaar na die voorgestelde verandering kyk en dit merge, verwerp of daarop reageer. Kom ons maak of die idee hom aanspreek, maar hy wil hê die lig moet 'n bietjie langer af as aan wees.

Waar hierdie bespreking via e-pos sou kon plaasvind in die werksvloeie wat ons in Distributed Git gewys het, vind dit by GitHub aanlyn [online] plaas. Die projekeienaar kan die eenvormige verskil bekyk en 'n kommentaar los deur op een of meer reëls te klik.

PR reëlkommentaar
Figure 105. Kommentaar lewer op 'n spesifieke kodereël in 'n Pull Request

Sodra die onderhouer [maintainer] hierdie kommentaar gemaak het, sal die persoon wat die Pull Request oopgemaak het (en enigiemand anders wat hierdie bewaarplek volg) 'n boodskap ontvang. Ons sal binnekort behandel hoe hierdie aangepas kan word, maar as hy e-poskennisgewings [email notifications] aan het, sou Tony 'n e-pos soos hierdie kry:

E-poskennisgewing
Figure 106. Kommentaar gestuur as e-poskennisgewing

Dit is vir almal toegelaat om algemene kommentaar op die Pull Request te maak. In Pull Request-besprekingsbladsy kan ons 'n voorbeeld sien van die projekeienaar wat sowel 'n kodereël kommentarieer as daarna 'n algemene kommentaar in die besprekingsgedeelte los. Jy kan sien dat die kode-kommentare ook by die gesprek gevoeg word.

PR-besprekingsbladsy
Figure 107. Pull Request-besprekingsbladsy

Nou kan die bydraer sien wat hy moet doen om sy verandering aanvaar te kry. Gelukkig is dit ook baie maklik om te doen. Waar jy by e-pos jou reeks patches [patch series] moet hersaamstel en dit weer na die poslys [mailing list] moet indien, hoef jy met GitHub bloot weer na die onderwerptak te commit en te push. In Pull Request finaal is te sien dat die ou kode-kommentaar in die bygewerkte Pull Request ingevou is, aangesien dit gemaak is op kode wat sedertdien verander is.

Die byvoeg van commits by 'n bestaande Pull Request veroorsaak geen kennisgewing nie, so sodra Tony sy regstellings gepush het, besluit hy om 'n kommentaar te los om die projekeienaar in te lig dat hy die gevraagde verandering gemaak het.

PR finaal
Figure 108. Pull Request finaal

'n Interessante ding om op te let, is dat wanneer jy die Files Changed''-oortjie [tab] op hierdie Pull Request klik, jy die eenvormige'' [unified] verskil kry — daarmee word bedoel die uiteindelike opgehoopte verskil wat na jou hooftak ingevoer sal word as hierdie onderwerptak gemerge sou word. In git diff-terminologie wys dit eintlik outomaties git diff master…​<branch> vir die tak waarop hierdie Pull Request gebaseer is. Sien Bepaling van Wat Ingestel Is (Determining What Is Introduced) vir meer inligting oor hierdie tipe verskil.

Die ander ding wat jy sal sien, is dat GitHub kontroleer of die Pull Request goed sal merge, en 'n knoppie bied om die merge namens jou op die bediener [server] te doen. Hierdie knoppie sien jy net as jy skryfregte op die bewaarplek het en 'n triviale merge moontlik is. As jy die knoppie klik, sal GitHub 'n ``non-fast-forward''-merge uitvoer, wat beteken dat selfs al sou die merge 'n fast-forward kon wees, dit steeds 'n merge-commit skep.

As jy dit eerder verkies, kan jy die tak eenvoudig pull en dit plaaslik merge. As jy hierdie tak in die master-tak merge en dit na GitHub push, word die Pull Request outomaties gesluit.

Dit is die eenvoudige werksvloei wat die meeste GitHub-projekte gebruik. Onderwerptakke word geskep, Pull Requests word daarop oopgemaak, 'n bespreking volg, moontlik word meer werk op die tak gedoen, en uiteindelik word die versoek gesluit of gemerge.

Note
Nie net forks nie

Dit is belangrik om op te let dat jy ook 'n Pull Request tussen twee takke in dieselfde bewaarplek kan oopmaak. As jy met iemand saamwerk aan 'n funksie [feature] en julle het albei skryfregte op die projek, kan jy 'n onderwerptak na die bewaarplek push en 'n Pull Request na die master-tak van dieselfde projek oopmaak om die kodenagaan- en besprekingsproses te begin. Fork is nie nodig nie.

Pull Requests vir gevorderdes

Noudat ons die grondbeginsels van bydra tot 'n projek op GitHub behandel het, kom ons wys 'n paar interessante wenke en truuks met betrekking tot Pull Requests sodat jy nog effektiewer kan wees in die gebruik daarvan.

Pull Requests as pleisters (patches [patches])

Dit is belangrik om te verstaan dat baie projekte Pull Requests nie regtig sien as stapels perfekte patches wat altyd netjies agtermekaar toegepas sal kan word nie, soos die meeste poslys-gebaseerde projekte die reeks bygedraagde patches sien. Die meeste GitHub-projekte sien Pull Request-takke as iteratiewe gesprekke rondom 'n voorgestelde verandering, wat uitloop op 'n eenvormige verskil wat met 'n merge toegepas word.

Dit is 'n belangrike onderskeid, want die verandering word oor die algemeen voorgestel voordat die kode as perfek beskou word, wat skaarser is by die reeks patch-bydraes op poslyste. Dit maak 'n vroeë gesprek met die onderhouers moontlik, sodat om 'n goeie oplossing te vind meer 'n poging van die hele gemeenskap word. As kode voorgestel word met 'n Pull Request en die onderhouers of die gemeenskap 'n verandering voorstel, word die reeks patches nie hersaamgestel nie; in plaas daarvan word die verskil as 'n nuwe commit op die tak gepush, terwyl die gesprek voortgaan met behoud van die konteks van die vorige werk.

Byvoorbeeld, as jy na Pull Request finaal terugkyk, sal jy sien dat die bydraer sy commit nie gerebase het en 'n ander Pull Request gestuur het nie. In plaas daarvan is nuwe commits bygevoeg en na die bestaande tak gepush. Op hierdie manier kan jy in die toekoms na hierdie Pull Request teruggaan en al die konteks terugvind waarop besluite geneem is. Die ``Merge''-knoppie op die webwerf te druk skep opsetlik 'n merge-commit wat na die Pull Request verwys, sodat dit maklik is om terug te gaan en die oorspronklike gesprek te ondersoek indien nodig.

Byhou met die upstream

As jou Pull Request verouder raak of om 'n ander rede nie skoon merge nie, sal jy dit wil regmaak sodat die onderhouer dit maklik kan merge. GitHub sal dit vir jou kontroleer en jou onderaan elke Pull Request laat weet of die merge triviaal is of nie.

PR-merge misluk
Figure 109. Pull Request sal nie netjies merge nie

As jy iets soos Pull Request sal nie netjies merge nie sien, sal jy jou tak wil regmaak sodat dit groen word en die onderhouer nie ekstra werk hoef te doen nie.

Jy het twee voor-die-hand-liggende opsies om dit te doen. Jy kan jou tak rebase op waar die teiken-tak [target branch] is (gewoonlik die master-tak van die bewaarplek wat jy geforkit het), of jy kan die teiken-tak in jou eie tak merge.

Die meeste ontwikkelaars op GitHub sal laasgenoemde doen, om dieselfde redes wat ons in die vorige paragraaf behandel het. Waaroor dit gaan, is die geskiedenis en die laaste merge; rebase gee jou dus nie veel meer as 'n effens skoner geskiedenis nie, en is aan die ander kant baie moeiliker en foutgevoelig.

As jy die teiken-tak wil merge om jou Pull Request merge-baar te maak, moet jy die oorspronklike bewaarplek as 'n nuwe afgeleë verwysing [remote] byvoeg, daarvan fetch, die hooftak van daardie bewaarplek in jou onderwerptak merge, die probleme oplos as daar enige is, en daarna jou onderwerptak weer na dieselfde tak push as waar jy die Pull Request op oopgemaak het.

As voorbeeld, kom ons neem aan dat in die ``tonychacon''-voorbeeld wat ons vantevore gebruik het, die oorspronklike outeur 'n verandering gemaak het wat 'n konflik in die Pull Request veroorsaak. Kom ons loop deur die stappe.

$ 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 die oorspronklike bewaarplek as afgeleë verwysing by met die naam ``upstream''

  2. Fetch die nuutste werk vanaf daardie afgeleë verwysing

  3. Merge die hooftak in jou onderwerptak

  4. Los die konflik op wat voorgekom het

  5. Push na dieselfde onderwerptak

Sodra jy dit gedoen het, sal die Pull Request outomaties opgedateer word en weer kontroleer word of dit skoon merge.

PR reggemaak
Figure 110. Pull Request merge goed

Een van die wonderlike dinge van Git is dat jy dit voortdurend kan bly doen. As jy 'n baie langlopende projek het, kan jy eenvoudig keer op keer die teiken-tak merge, en hoef jy net die konflikte op te los wat ontstaan het sedert die vorige keer dat jy gemerge het, wat die proses baie hanteerbaar maak.

As jy regtig die tak wil rebase om dit op te ruim, kan jy dit gerus doen, maar dit word sterk aangeraai om nie te forseer-push [force push] na die tak waarop reeds 'n Pull Request oopgemaak is nie. As ander mense dit gepull het en daarop begin voortwerk het, sal jy met al die probleme te doen kry wat genoem is in Die Gevare van Rebasing (The Perils of Rebasing). In plaas daarvan push jy die gerebasede tak na 'n nuwe tak op GitHub en maak 'n splinternuwe Pull Request oop waarin jy na die ou een verwys, en sluit daarna die oorspronklike versoek.

Verwysings

Jou volgende vraag mag wees ``Hoe verwys ek na die ou Pull Request?'' Daar blyk baie, baie maniere te wees waarop jy na ander dinge kan verwys, so ongeveer oral waar jy op GitHub kan skryf.

Kom ons begin met hoe om na 'n ander Pull Request of Issue te verwys. Alle Pull Requests en Issues het 'n nommer toegeken gekry, en hierdie is uniek binne die projek. Byvoorbeeld, jy kan nie Pull Request 3 en Issue #3 hê nie. As jy na enige Pull Request of Issue vanuit 'n ander wil verwys, kan jy eenvoudig <num> in enige kommentaar of beskrywing neersit. Jy kan meer spesifiek wees as die Issue of Pull Request elders bestaan; skryf gebruikersnaam#<num> as jy verwys na 'n Issue of Pull Request in 'n fork of bewaarplek waarin jy is, of gebruikersnaam/repo#<num> om te verwys na iets in 'n ander bewaarplek.

Kom ons kyk na 'n voorbeeld. Stel ons het die tak in die vorige voorbeeld gerebase, 'n nuwe pull request daarvoor geskep, en nou wil ons verwys na die ou pull request vanuit die nuwe een. Ons wil ook verwys na 'n issue in die fork van die bewaarplek in 'n heel ander projek. Ons maak die beskrywing soos in Verwysings in 'n Pull Request..

PR-verwysings
Figure 111. Verwysings in 'n Pull Request.

As ons hierdie pull request indien, sien ons dit alles vertoon soos in Verwysings vertoon in 'n Pull Request..

PR-verwysings vertoon
Figure 112. Verwysings vertoon in 'n Pull Request.

Let daarop dat die volledige GitHub-URL wat ons ingesit het, verkort is tot net die nodige inligting.

As Tony nou die oorspronklike Pull Request sluit, sien ons dit omdat ons dit in die nuwe een vermeld het — GitHub het outomaties 'n terugverwysingsgebeurtenis [backlink event] in die tydlyn van die Pull Request geskep. Dit beteken dat enigiemand wat hierdie Pull Request besoek en sien dat dit gesluit is, maklik kan terugskakel na die een wat dit oorvleuel/vervang. Die skakel sal lyk soos in Verwysing vertoon in 'n Pull Request..

PR gesluit
Figure 113. Verwysing vertoon in 'n Pull Request.

Benewens issue-nommers, kan jy ook na 'n spesifieke commit verwys deur middel van die SHA-1. Jy moet 'n volledige 40-karakter SHA-1 vermeld, maar as GitHub dit in 'n kommentaar sien, sal dit direk na die commit skakel. Weereens kan jy na commits in forks of ander bewaarplekke verwys op dieselfde manier as wat jy met issues gedoen het.

Markdown met 'n GitHub-geurtjie (GitHub Flavored Markdown [GitHub Flavored Markdown])

Skakel na ander Issues is maar die begin van die interessante dinge wat jy met byna enige teksveld op GitHub kan doen. In Issue- en Pull Request-beskrywings, kommentare, kode-kommentare en ander plekke kan jy die sogenaamde ``GitHub Flavored Markdown'' gebruik. Markdown is soos om in gewone teks te skryf, maar met meer funksionaliteit wanneer dit vertoon word.

Sien 'n Voorbeeld van Markdown soos geskryf en vertoon. vir 'n voorbeeld van hoe kommentaar of teks geskryf en daarna met Markdown vertoon kan word.

Voorbeeld Markdown
Figure 114. 'n Voorbeeld van Markdown soos geskryf en vertoon.

Die geurtjie wat GitHub aan Markdown byvoeg, is meer as wat jy met standaard Markdown kry. Hierdie geurtjies kan almal baie nuttig wees as jy bruikbare Pull Request- of Issue-kommentaar of -beskrywings skep.

Taaklyste (task lists [task lists])

Die eerste werklik bruikbare GitHub-spesifieke Markdown-opsie, veral vir gebruik in Pull Requests, is die taaklys. 'n Taaklys is 'n lys merkblokkies [checkboxes] van dinge wat jy gedoen wil hê. Om dit in 'n Issue of Pull Request neer te sit, wys gewoonlik die dinge wat jy gedoen wil hê voordat jy die onderwerp as gesluit beskou.

Jy kan op hierdie manier 'n taaklys skep:

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

As ons hierdie in die beskrywing van 'n Pull Request of Issue sit, sal ons dit sien vertoon soos in Taaklyste soos vertoon in 'n Markdown-kommentaar.

voorbeeld taaklys
Figure 115. Taaklyste soos vertoon in 'n Markdown-kommentaar.

Dit word dikwels in 'n Pull Request gebruik om aan te dui wat jy alles op die tak gedoen wil sien voordat die Pull Request gereed is om te merge. Die werklik gawe ding hiervan is dat jy eenvoudig op die merkblokkies kan klik om die kommentaar by te werk — jy hoef nie die teks van die Markdown self te verander om die take af te merk nie.

En daar is meer: GitHub sal na taaklyste soek in jou Issues en Pull Requests en dit as metadata op die bladsy vertoon wat hulle bevat. Byvoorbeeld, as jy 'n Pull Request met take het en jy kyk na die oorsigbladsy van alle Pull Requests, kan jy sien hoe ver dit gereed is. Dit help mense om Pull Requests in subtake in te deel, en ander mense om die vordering van die tak te volg. Jy kan 'n voorbeeld hiervan sien in Opsomming van taaklyste in die Pull Request-lys..

Voorbeeld taaklys
Figure 116. Opsomming van taaklyste in die Pull Request-lys.

Dit is uiters handig as jy vroeg 'n Pull Request oopmaak en dit gebruik om die vordering tydens die implementering van die funksie te volg.

Kodegreepies (code snippets [code snippets])

Jy kan ook kodegreepies by kommentare voeg. Dit is veral handig as jy iets wil voorstel wat jy sou kon probeer doen voordat jy dit werklik as 'n commit in jou tak implementeer. Dit word ook dikwels gebruik om 'n voorbeeld te gee van kode wat nie werk nie, of wat in hierdie Pull Request geïmplementeer sou kon word.

Om 'n kodegreepie by te voeg, moet jy dit met 'omgekeerde kommas' (backticks [backticks]) omsluit.

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

As jy die naam van die taal byvoeg, soos ons hier met 'java' gedoen het, sal GitHub ook probeer om die sintaks te merk [syntax highlighting]. In die bostaande voorbeeld sou dit vertoon word soos in Vertoonde omsluite kodevoorbeeld..

Vertoonde omsluite kode
Figure 117. Vertoonde omsluite kodevoorbeeld.

Aanhaal (quoting [quoting])

As jy op 'n klein deel van 'n lang kommentaar reageer, kan jy na keuse aanhaal uit die ander kommentaar deur die reël met die >-teken te laat begin. Dit is so algemeen en bruikbaar dat daar 'n sleutelbordkortpad [keyboard shortcut] daarvoor geskep is. As jy die teks selekteer in die kommentaar waarop jy direk wil reageer en die r-sleutel druk, word dit outomaties as aanhaling in die kommentaarruimte vir jou geplaas.

Die aanhalings lyk ongeveer so:

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

Sodra dit vertoon word, sal die kommentaar lyk soos in Vertoonde aanhalingsvoorbeeld..

Vertoonde aanhaling
Figure 118. Vertoonde aanhalingsvoorbeeld.

Emoji

Laastens kan jy ook emoji in jou kommentaar gebruik. Dit word eintlik redelik gereeld gebruik in die kommentare wat jy by baie GitHub-issues en Pull Requests sien. Daar is selfs 'n emoji-hulpmiddel op GitHub. As jy 'n kommentaar intik en met 'n :-teken begin, sal 'n outovoltooiingshulp [autocomplete] jou kom help om te vind wat jy soek.

Emoji-voltooiingshulp
Figure 119. Emoji-voltooiingshulp in aksie.

Emoji’s lyk soos :<naam>: iewers in jou kommentaar. Jy sou byvoorbeeld iets soos hierdie kon skryf:

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:

Wanneer dit vertoon word, lyk dit soos in Swaar emoji-kommentaar..

Emoji
Figure 120. Swaar emoji-kommentaar.

Dit voeg nie regtig veel inhoudelik by nie, maar dit gee wel 'n bietjie kleur en emosie aan 'n medium wat gewoonlik nogal moeilik emosies kan weergee.

Note

Daar is deesdae nogal 'n paar webdienste wat van emoji gebruik maak. 'n Goeie spiekbrief om emoji te vind wat uitdruk wat jy wil sê, kan jy vind by:

http://www.emoji-cheat-sheet.com

Prente (images [images])

Streng gesproke is dit nie 'n GitHub-geurtjie van Markdown nie, maar dit is baie handig. Benewens die byvoeg van Markdown-prentskakels [image links] aan kommentaar, waarvoor dit moeilik kan wees om URL’s te vind en in te voeg, laat GitHub jou toe om prente te sleep-en-los [drag & drop] in teksareas om hulle in te voeg.

Prente sleep-en-los
Figure 121. Sleep-en-los van prente om hulle op te laai en outomaties in te voeg.

As jy terugkyk na Verwysings in 'n Pull Request., kan jy 'n klein ``Parsed as Markdown''-leidraad bo die teksarea sien. As jy hierop klik, sal dit vir jou 'n volledige spiekbrief wys van alles wat jy met Markdown op GitHub kan doen.

Hou jou openbare GitHub-bewaarplek op datum

Sodra jy 'n GitHub-bewaarplek geforkit het, bestaan jou bewaarplek (jou "fork") onafhanklik van die oorspronklike een. Spesifiek, as die oorspronklike bewaarplek nuwe commits het, stel GitHub jou in kennis met 'n boodskap soos hierdie:

This branch is 5 commits behind progit:master.

Maar jou GitHub-bewaarplek sal nooit outomaties deur GitHub bygewerk word nie; dit is iets wat jy self moet doen. Gelukkig is dit baie maklik om te doen.

Een moontlikheid om dit te doen vereis geen konfigurasie nie. Byvoorbeeld, as jy van https://github.com/progit/progit2.git geforkit het, kan jy jou master-tak soos volg op datum hou:

$ git checkout master (1)
$ git pull https://github.com/progit/progit2.git (2)
$ git push origin master (3)

  1. As jy op 'n ander tak is, keer terug na master.

  2. Fetch veranderinge vanaf https://github.com/progit/progit2.git en merge dit in master.

  3. Push jou master-tak na origin.

Dit werk, maar dit is 'n bietjie vervelig om elke keer die volledige fetch-URL te moet intik. Jy kan dit met 'n bietjie konfigurasie outomatiseer.

$ 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 die bronbewaarplek by en gee dit 'n naam. Hier het ek die naam progit gekies

  2. Stel jou master-tak in om vanaf die progit-afgeleë verwysing te fetch.

  3. Sorg dat die standaard push-bewaarplek origin is.

Sodra dit gedoen is, word die werksvloei baie eenvoudiger:

$ git checkout master (1)
$ git pull (2)
$ git push (3)

  1. As jy op 'n ander tak is, keer terug na master.

  2. Fetch veranderinge vanaf progit en merge dit in master.

  3. Push jou master-tak na origin.

Hierdie benadering kan handig wees, maar dit is nie sonder nadele nie. Git sal blymoedig al hierdie werk stilweg vir jou doen, maar dit sal jou nie waarsku as jy 'n commit na master doen, van progit pull en dan na origin push nie; al hierdie handelinge is geldig met hierdie opset. Jy moet dus goed oplet om nooit direk na master te commit nie, aangesien daardie tak effektief aan 'n voorafgaande bewaarplek behoort.