6.2 GitHub - Prispevek k projektu

Tony išče kodo, ki bi jo lahko izvajal na svojem programabilnem mikrokrmilniku Arduino, in je našel odlično programsko datoteko na GitHubu na https://github.com/schacon/blink.

Edini problem je, da je utripanje prehitro. Menimo, da je veliko lepše počakati 3 sekunde namesto 1 med vsako spremembo stanja. Torej izboljšajmo program in ga predložimo nazaj v projekt kot predlagano spremembo.

Najprej kliknemo gumb »Fork«, kot je že omenjeno, da dobimo lastno kopijo projekta. Naše uporabniško ime tukaj je »tonychacon«, torej je naša kopija tega projekta na https://github.com/tonychacon/blink, kjer ga lahko urejamo. Lokalno ga bomo klonirali, ustvarili tematsko vejo, naredili spremembo v kodi in nazadnje to spremembo potisnili nazaj na GitHub.

Če se vrnemo na svojo razvejitev projekta na GitHubu, lahko vidimo, da je GitHub opazil, da smo potisnili novo tematsko vejo in nam predstavi velik zelen gumb, s katerim lahko preverimo svoje spremembe in odpremo zahtevek potega na originalni projekt.

Namesto tega lahko greste na stran »Branches« na https://github.com/<user>/<project>/branches, da najdete svojo vejo, in od tam odprete nov zahtevek potega.

Če kliknemo ta zeleni gumb, bomo videli zaslon, ki nas prosi, da dodelimo svojemu zahtevku potega naslov in opis. Skoraj vedno se splača v to vložiti nekaj truda, saj dober opis pomaga lastniku originalnega projekta ugotoviti, kaj ste poskušali storiti, ali so vaše predlagane spremembe pravilne in ali bi sprejetje sprememb izboljšalo izvirni projekt.

Prav tako vidimo seznam potrditev v svoji tematski veji, ki so »naprej« od glavne veje master (v tem primeru samo ena) in združeno razliko vseh sprememb, ki bodo narejene, če bo ta veja združena s strani lastnika projekta.

Ko pritisnete gumb »Create pull request« na tej strani, bo lastnik projekta, ki ste ga razvejali, prejel obvestilo, da nekdo predlaga spremembo in bo dobil povezavo do strani, ki vsebuje vse te informacije.

V tem trenutku lahko lastnik projekta pregleda predlagano spremembo in jo združi, zavrne, ali nanjo komentira. Recimo, da mu je ideja všeč, vendar bi raje imel malo daljši čas za izklop kot vklop luči.

Medtem ko se lahko ta pogovor odvija preko e-pošte v potekih dela, predstavljenih v poglavju Porazdeljeni Git, se na GitHubu to zgodi na spletu. Lastnik projekta lahko pregleda združeno razliko (angl. diff) in pusti komentar, tako da klikne na katero koli od vrstic.

Ko vzdrževalec napiše ta komentar, bo oseba, ki je odprla zahtevek potega (in vsakdo drug, ki spremlja ta repozitorij), prejela obvestilo. Kasneje bomo opisali, kako lahko prilagodite ta obvestila, vendar če ima Tony vklopljena obvestila po e-pošti, bi prejel e-poštno sporočilo takole:

Kdor koli lahko tudi pusti splošne komentarje na zahtevku potega. Na sliki Stran za diskusijo zahtevka potega lahko vidimo primer, ko lastnik projekta komentira vrstico kode in nato pusti splošen komentar v razdelku za razpravo. Vidite lahko, da so komentarji kode prav tako vključeni v pogovor.

Sedaj lahko sodelujoči vidi, kaj mora storiti, da bo njegova sprememba sprejeta. Na srečo je to zelo preprosto. Kjer bi morali preko e-pošte ponovno uvrstiti svojo serijo in jo ponovno poslati na seznam za pošiljanje, lahko preko GitHuba preprosto spet potrdite na svoji tematski veji in jo potisnete, kar bo samodejno posodobilo zahtevek potega. Na sliki Končni zahtevek potega lahko vidite tudi, da je bil star komentar kode zložen v posodobljenem zahtevku potega, saj je bil narejen na vrstici, ki je bila od takrat spremenjena.

Dodajanje potrditev k obstoječemu zahtevku potega ne sproži obvestila, zato se Tony odloči, da bo pustil komentar, da obvesti lastnika projekta, da je izvedel zahtevano spremembo.

Zanimivo je opaziti, da če kliknete na zavihek »Files Changed« na tem zahtevku potega, boste dobili »združeno« razliko — torej skupno razliko, ki bi jo v glavno vejo uvedli, če bi bila ta tematska veja združena. V pojmu git diff vam to v bistvu avtomatično prikaže git diff master…​<branch> za vejo, na kateri temelji ta zahtevek potega. Za več informacij o tej vrsti razlike si oglejte razdelek Določanje, kaj se uvaja.

Druga stvar, ki jo boste opazili, je, da GitHub preveri, ali se zahtevek potega združi brez težav, in ponudi gumb za izvedbo združevanja na strežniku. Ta gumb se prikaže le, če imate dostop za pisanje v repozitoriju in če je mogoča trivialna združitev. Če nanj kliknete, bo GitHub izvedel združitev »non-fast-forward«, kar pomeni, da bo ustvaril potrditev združitve, tudi če bi lahko združitev bila hitro previta naprej.

Če želite, lahko preprosto povlečete vejo navzdol in jo lokalno združite. Če to vejo združite v vejo master in jo potisnete na GitHub, bo zahtevek potega samodejno zaprt.

To je osnovni potek dela, ki ga uporablja večina projektov na GitHubu. Ustvarijo se tematske veje, nanje se odprejo zahtevki potegov, sledi razprava, morda se na veji opravi še več dela, dokler zahtevek ni zaprt ali združen.

Pomembno je razumeti, da se mnogi projekti ne osredotočajo na zahtevke potegov kot vrste popolnih popravkov, ki se lahko uporabijo brezhibno po vrstnem redu, kot to velja za projekte, ki temeljijo na elektronski pošti. Večina projektov na GitHubu razmišlja o vejah zahtevkov potegov kot o iterativnih pogovorih o predlagani spremembi, ki se končajo s skupno razliko, ki se uporablja z združevanjem.

To je pomembna razlika, saj se sprememba po navadi predlaga, preden se koda šteje za popolno, kar je pri popravkih po serijah, ki temeljijo na elektronski pošti, veliko manj pogosto. To omogoča prejšnji pogovor z vzdrževalci, da bi prišli do prave rešitve, ki je bolj prizadevanje skupnosti. Ko se z zahtevkom potega predlaga koda in vzdrževalci ali skupnost predlagajo spremembo, se serija popravkov ponavadi ne prenese na novo, temveč se razlika pošlje kot novo potrditev na veji, kar pomaga pri nadaljnjem pogovoru ob ohranjanju konteksta prejšnjega dela.

Na primer, če se vrnete in si ponovno ogledate sliko Končni zahtevek potega, boste opazili, da predlagatelj ni preklopil svoje potrditve in poslal novega zahtevka potega. Namesto tega je dodal nove potrditve in jih potisnil v obstoječo vejo. Tako lahko, če se v prihodnosti vrnete in si ogledate ta zahtevek potega, enostavno najdete celoten kontekst odločitev. Pritisk na gumb »Merge« na spletnem mestu namenoma ustvari potrditev združitve, ki se sklicuje na zahtevek potega, tako da se je enostavno vrniti in preučiti prvotni pogovor, če je to potrebno.

Če vaš zahtevek potega zastara ali se na drugačen način ne združi gladko, ga boste želeli popraviti, da ga lahko vzdrževalec enostavno združi. GitHub bo to preizkusil za vas in vam sporočil na dnu vsakega zahtevka potega, ali je združevanje trivialno ali ne.

Če vidite kaj takega, kot je prikazano na sliki Zahtevek potega se ne združi gladko, boste želeli popraviti svojo vejo, da se obarva zeleno in vzdrževalcu ne bo treba opravljati dodatnega dela.

Imate dve glavni možnosti, da to storite. Lahko ponovno bazirate svojo vejo na vrhu ciljne veje (običajno veje master repozitorija, ki ste ga klonirali), ali pa ciljno vejo združite v svojo vejo.

Večina razvijalcev na GitHubu se odloči za slednjo možnost iz istih razlogov, ki smo jih pravkar obravnavali v prejšnjem odstavku. Pomembna je zgodovina in končno združevanje, zato ponovno baziranje ne prinaša veliko drugega kot nekoliko bolj čisto zgodovino, v zameno pa je veliko težje in bolj nagnjeno k napakam.

Če želite združiti ciljno vejo, da bo vaš zahtevek potega združljiv, dodate izvirni repozitorij kot nov oddaljeni vir, ga prenesete, združite glavno vejo tega repozitorija v svojo tematsko vejo, odpravite morebitne težave in ga nazadnje znova naložite v isto vejo, na kateri ste odprli zahtevek potega.

Na primer, recimo, da je prvotni avtor v primeru »tonychacon«, ki smo ga uporabljali prej, naredil spremembo, ki bi povzročila konflikt v zahtevku potega. Pojdimo skozi te korake.

Ko to storite, bo zahtevek potega samodejno posodobljen in ponovno preverjen, če se gladko združi.

Ena od odličnih lastnosti Gita je, da to lahko storite neprekinjeno. Če imate zelo dolgotrajen projekt, lahko enostavno združujete s ciljno vejo znova in znova ter se ukvarjate le s konflikti, ki so se pojavili od zadnjega združevanja, kar olajša postopek.

Če absolutno želite preurediti vejo, da jo očistite, to zagotovo lahko storite, vendar močno priporočamo, da ne potisnete prisilno preko veje, na kateri je že odprt zahtevek potega. Če so jo druge osebe povlekle in nanjo dodale več dela, se srečate z vsemi težavami, ki so opisane v razdelku Nevarnosti ponovnega baziranja. Namesto tega potisnite ponovno bazirano vejo v novo vejo na GitHubu in odprite povsem nov zahtevek potega, ki se sklicuje na starega, nato pa zaprite izvirnega.

Vaše naslednje vprašanje je morda »Kako se sklicujem na stari zahtevek potega?«. Izkazalo se je, da obstaja veliko načinov za sklicevanje na druge stvari skoraj povsod, kjer lahko pišete na GitHubu.

Začnimo s tem, kako se sklicevati na drugi zahtevek potega ali težavo. Vse zahtevke potegov in težave imajo dodeljene številke in so edinstvene v projektu. Na primer, ne morete imeti zahtevka potega #3 in težave #3. Če se želite sklicevati na kateri koli zahtevek potega ali težavo od drugod, lahko preprosto vstavite #<številka> v kateri koli komentar ali opis. Lahko pa ste bolj natančni, če je težava ali zahtevek potega drugje; napišite uporabniško_ime#<num>, če se sklicujete na težavo ali zahtevek potega v razvejitvi repozitorija, v katerem ste, ali uporabniško_ime/repo#<num> za sklicevanje na kaj v drugem repozitoriju.

Poglejmo primer. Recimo, da smo preuredili vejo v prejšnjem primeru, ustvarili nov zahtevek potega in zdaj se želimo v novem sklicevati na stari zahtevek potega. Želimo se tudi sklicevati na težavo v razvejitvi repozitorija in težavo v popolnoma drugem projektu. Opis lahko izpolnite enako kot v razdelku Navzkrižno sklicevanje v zahtevku potega.

Ko bomo oddali ta zahtevek potega, bomo videli, da se bo vse to prikazalo tako kot na sliki Navzkrižne reference, upodobljene v zahtevku potega.

Opazite, da se je celoten URL na GitHubu, ki smo ga vnesli, skrajšal le na informacije, ki so potrebne.

Če Tony zdaj zapre prvotni zahtevek potega, lahko vidimo, da je GitHub avtomatično ustvaril sledilni dogodek v časovnici zahtevka potega, ker smo ga omenili v novem zahtevku. To pomeni, da lahko kdorkoli, ki obišče ta zahtevek potega, vidi, da je zaprt, in enostavno poveže nazaj s tistim, ki ga je nadomestil. Povezava bo videti nekako tako kot na sliki Povezava nazaj na nov zahtevek potega na zaprti časovnici zahtevka potega.

Poleg številk težav lahko na enak način kot referenčne oznake uporabimo tudi identifikatorje SHA-1 določenih potrditev. Pri tem je treba navesti celotnih 40 znakov identifikatorja SHA-1, vendar bo GitHub v komentarju takoj ustvaril povezavo do ustrezne potrditve. Kot pri težavah lahko tudi pri potrditvah v drugih razvejitvah ali repozitorijih uporabimo enak način referenciranja potrditev.

Prva resnično uporabna funkcija specifična za GitHub Markdown, še posebej za uporabo pri zahtevkih potegov, je seznam opravil. Seznam opravil je seznam polj z oznakami za stvari, ki jih želite opraviti. Postavitev seznama v težavo ali zahtevek potega običajno pomeni, da želite te stvari opraviti, preden štejete element za dokončanega.

Seznam opravil lahko ustvarite tako:

Če to vključimo v opis zahtevka potega ali težave, bomo videli, da se bo prikazal kot na Seznami opravil, upodobljeni v komentarju Markdown.

To se pogosto uporablja pri zahtevkih potegov, da bi označili, kaj vse bi radi dokončali na veji, preden bo zahtevek potega pripravljen za združevanje. Res odličen del je, da lahko preprosto kliknete polja z oznakami, da posodobite komentar — ne potrebujete urejanja Markdowna neposredno za označevanje opravil.

Poleg tega bo GitHub iskal sezname opravil v vaših težavah in zahtevkih potegov ter jih prikazal kot metapodatke na straneh, ki jih naštevajo. Na primer, če imate zahtevek potega z nalogami in si ogledate pregledno stran vseh zahtevkov potegov, lahko vidite, kako daleč je že opravljeno. To pomaga ljudem razbiti zahtevke potegov na podnaloge in drugim ljudem pomagati pri spremljanju napredka veje. Primer tega lahko vidite na sliki Povzetek seznama opravil na seznamu zahtevkov potegov.

Ti seznami so izjemno uporabni, ko odprete zahtevek potega zgodaj in ga uporabite za spremljanje svojega napredka pri izvedbi funkcionalnosti.

V komentarje lahko dodate tudi delčke kode. To je še posebej uporabno, če želite nekaj predstaviti, kar bi lahko poskusili pred dejansko izvedbo kot potrditev na vaši veji. Pogosto se to uporablja tudi za dodajanje primerne kode o tem, kaj ne deluje, ali kaj bi lahko ta zahtevek potega implementiral.

Da dodate delček kode, ga morate »ograditi« v leve črtice.

Če dodate ime jezika, kot smo to storili z java, bo GitHub poskusil tudi poudariti sintakso delčka kode. V zgornjem primeru bo prikazan kot Primer upodobljene ograjene kode.

Če se odzivate na majhen del dolgega komentarja, lahko selektivno citirate iz drugega komentarja tako, da vrstice predhodno označite z znakom >. Dejansko je tako običajno in uporabno, da obstaja bližnjica na tipkovnici. Če v komentarju označite besedilo, na katero želite neposredno odgovoriti, in pritisnete tipko r, bo besedilo citirano v polju za komentarje.

Citati so videti nekako takole:

Ko je komentar prikazan, bo videti nekako tako kot na sliki Prikazan primer citiranja.

Končno lahko v svojih komentarjih uporabljate tudi emodžije. To se dejansko precej pogosto uporablja v komentarjih, ki jih vidite v mnogih težavah in zahtevkih potegov na GitHubu. Na GitHubu je na voljo tudi pomočnik za emodžije. Če vnesete komentar in začnete z znakom :, bo pomočnik za samodokončanje pomagal najti tisto, kar iščete.

Emodžiji imajo obliko :<ime>: kjerkoli v komentarju. Na primer, napišete lahko nekaj takega:

Ko je prikazano, bi bilo videti nekako tako kot na sliki Komentiranje z veliko emodžiji.

Čeprav to ni izjemno koristno, vseeno doda element zabave in čustev v medij, v katerem je sicer težko izraziti čustva.

To ni tehnično GitHub Flavored Markdown, vendar pa je izjemno koristno. Poleg dodajanja slikovnih povezav Markdown v komentarje, kar lahko zahteva iskanje in vdelavo URL-jev, vam GitHub omogoča, da slike povlečete in spustite v tekstovna področja, da jih vdelate.

Če pogledate na sliko Povlecite in spustite slike, da jih naložite in avtomatsko vdelate, lahko vidite majhen namig »Parsed as Markdown« nad besedilnim poljem. Če nanj kliknete, se vam bo prikazal celoten seznam vsega, kar lahko storite z Markdownom na GitHubu.