4.2 GitHub - Как да сътрудничим в проект

Да кажем, че Tony търси определен код, който да стартира на своя програмируем микроконтролер Arduino и го е открил в GitHub хранилището на адрес https://github.com/schacon/blink.

Кодът е ОК, единственият проблем е, че скоростта на примигване е твърде висока и решаваме да я намалим до веднъж на 3 секунди, вместо всяка секунда. Така че, нека променим програмата и да изпратим промяната си като предложим тя да бъде интегрирана в главния проект.

Първо, натискаме бутона 'Fork', за да си създаден собствено копие на проекта. Потребителското ни име е “tonychacon”, така че нашето копие на този проект ще е на адрес https://github.com/tonychacon/blink и там ще можем да пишем. Ще си го клонираме локално в компютъра, ще създадем topic клон, ще променим необходимото и ще изпратим промените обратно към GitHub.

Сега, ако се върнем обратно в сайта с нашето копие, ще видим че GitHub е установил, че сме публикували нов topic клон и ще ни предложи голям зелен бутон с чиято помощ да проверим промените и да създадем Pull Request към оригиналния проект.

Можете също така да отворите “Branches” страницата на адрес https://github.com/<user>/<project>/branches за да намерите вашия клон и да създадете Pull Request директно оттам.

Ако натиснем бутона, ще видим екран, който ни подканя да въведем заглавие и описание на нашия Pull Request. Почти винаги това усилие си струва, защото подходящото пояснение ще улесни собственика на проекта да разбере по-лесно целта на вашите промени, дали те са коректни и дали наистина подобряват проекта като цяло.

Също така, виждаме списък с къмитите на нашия topic клон, които са “ahead” (напред) в сравнение с master клона (в този случай, само един къмит) и унифициран diff със всички промени, които ще бъдат направени в проекта, ако собственикът му реши да направи сливането.

Когато натиснете бутона 'Create pull request' на този екран, собственикът на оригиналния проект ще получи уведомление, че някой предлага промяна и линк към страница описваща всички промени.

В този момент, собственикът на проекта може да погледне промените ви и да ги приеме, да ги отхвърли или да ги коментира. Нека допуснем, че той харесва идеята ви, но би предпочел времето, в което светлината на платката е изключена, да е малко по-дълго от времето, в което е включена.

Докато цялата тази комуникация традиционно би се извършвала по имейл в работните процеси описани в [ch05-distributed-git], то в GitHub тя се осъществява онлайн. Собственикът може да разгледа унифицирания diff и да постави коментар щраквайки директно върху кой да е ред от кода.

Веднъж след като коментарът бъде направен, човекът отворил Pull Request-та (както и всички други следящи хранилището), ще получат уведомление за това. Ще видим това по-късно, но в общи линии, ако сме разрешили имейл нотификациите, Tony ще получи електронна поща с нещо подобно:

Също така, всеки може да остави общ коментар по Pull Request. В Страница за дискусии за Pull Request можем да видим пример, в който собственикът на проект коментира както даден ред код, така и да оставя общ коментар в секцията за дискусии. Можете да видите, че code-коментарите също се показват в дискусията.

Сега сътрудникът може да види какво трябва да коригира по кода си, за да бъде той приет за сливане. За щастие, това е доста лесно. Ако използвахте имейл, можеше да се наложи да съберете наново всичката информация и да я изпратите към мейлинг лист отново и отново. С GitHub обаче, вие просто къмитвате към topic клона, публикувате го в хранилището си и това автоматично обновява Pull Request-a. В Финален Pull Request можете също така да видите, че старият коментар в кода е свит в обновения Pull Request, тъй като е бил направен за ред, който после е бил променен.

Добавянето на къмити към съществуващ Pull Request не изпраща нови нотификации, така че след като Tony е публикувал корекциите си, той решава да остави коментар, за да информира собственика, че е направил исканите промени.

Интересно за отбелязване, ако кликнете върху секцията “Files Changed” на този Pull Request, ще получите т. нар. “unified” diff — това са общите сумарни промени, които ще бъдат въведени в главния клон на проекта, ако този topic клон бъде слят. В смисъла на git diff, това автоматично ви показва git diff master…​<branch> за клона, върху който е базиран този Pull Request. Вижте Изследване на промените за повече информация за този тип diff.

Другото, което ще забележите е, че GitHub проверява дали Pull Request-ът ви може да се слее чисто и ако е така - осигурява бутон да го направите директно на сървъра. Този бутон се показва само ако имате права за писане в хранилището и ако може да се направи тривиално сливане. Ако го натиснете, GitHub ще направи “non-fast-forward” сливане, което значи че дори сливането да би могло да бъде fast-forward, то все пак ще се създаде merge commit.

Ако предпочитате, бихте могли просто да изтеглите клона локално и да го слеете на компютър. Ако направите това и слеете клона с master клона и след това качите обратно в GitHub, то Pull Request-тът ще бъде автоматично затворен.

Това е базисният работен процес, който повечето GitHub проекти следват. Създават се topic клонове, по тях се отварят Pull Request-и, провежда се дискусия, евентуално се извършват допълнителни корекции и накрая Pull Request-ът или се приема или се затваря.

Важно е да се разбере, че много проекти в действителност не разглеждат Pull Request-ите като поредици от перфектни пачове, които трябва да се прилагат чисто в определена последователност както примерно се гледа на тях в проектите базирани на комуникация през мейлинг листи. Повечето GitHub проекти гледат на Pull Request клоновете като на итеративна дискусия около дадена предложена промяна, кулминацията на която е унифицирания diff, който се прилага при сливането.

Това е важна разлика, понеже в общия случай промяната се предлага преди кодът да е възприет като перфектен - нещо което се случва далеч по-рядко при мейлинг-лист базираните серии от пачове. Това позволява контакт със собственика на проекта на много по-ранен етап и съответно достигането до финалното решение на даден проблем е много повече плод на съвместни усилия. Когато с Pull Request се предложи код и собствениците на проекта или трети страни предложат промяна по него, серията пачове не се излива наново а вместо това се публикуват само разликите под формата на нов къмит в клона като дискусията се премества напред в контекста на вече създадената работа.

Ако се върнете малко назад и погледнете отново Финален Pull Request, ще забележите, че сътрудникът не е пребазирал къмита си и не е създавал нов Pull Request. Вместо това, той е създал няколко нови къмита и ги е публикувал в същия клон. По този начин, ако по-късно във времето се върнете и разгледате отново този Pull Request, ще можете лесно да намерите контекста в който дадените решения са били взети. Натискането на бутона “Merge” в сайта умишлено създава merge къмит, който сочи към Pull Request-а, така че е лесно да се върнете назад и да изследвате оригиналната дискусия, ако е необходимо.

Ако вашият Pull Request стане неактуален или по друга причина не се слива чисто, вероятно ще искате да го поправите, така че да може да бъде лесно слят от собственика на проекта на по-късен етап. GitHub ще тества това за вас и ще ви уведомява със съобщение в долната част на екрана на всеки Pull Request дали сливането е тривиално или не.

Ако видите нещо като Pull Request, който не се слива чисто, ще трябва да поправите вашия клон, така че да стане отново "зелен" и да не се налага собственикът на проекта да извършва допълнителни дейности.

Имате два начина да се оправите в подобни случаи. Можете или да пребазирате вашия клон върху целевия такъв (нормално master клона на хранилището, което сте fork-нали), или да слеете целевия клон с вашия.

Повечето разработчици в GitHub правят второто по същите причини, които разгледахме в предишната глава. Това, което е важно е историята и финалното сливане, така че пребазирането не ви дава много повече от една идея по-чиста история - а за сметка на това е много по-труден и податлив на грешки процес.

Ако решите да слеете актуалния целеви клон, така че Pull Request-ът ви да може да се слива, ще добавите оригиналното хранилище като нова отдалечена референция, ще издърпате данните от нея, ще слеете основния ѝ клон във вашия topic клон, ще поправите евентуалните проблеми и накрая ще изпратите промените в същия клон, от който сте създали Pull Request-а.

Например, нека кажем, че в “tonychacon” случая, който вече използвахме, оригиналният автор е направил промяна, която ще доведе до конфликт с нашия Pull Request. Нека следваме тази последователност:

След като направим това, Pull Request-ът ни автоматично ще бъде обновен и проверен дали се слива безконфликтно.

Едно от най-добрите неща в Git е, че можете да правите това непрекъснато. Ако имате много дълго продължаващ проект, можете спокойно да издърпвате и сливате главния му клон много пъти и само трябва да се справяте с евентуално възникналите конфликти след последното ви сливане, което прави процеса лесно управляем.

Ако все пак категорично искате да пребазирате клона, за да го прочистите, със сигурност можете да направите това, но горещо се препоръчва да не се презаписва клон от който има пуснат Pull Request. Ако други хора вече са го изтеглили и са работили по него, ще се сблъскате с всички проблеми посочени в [_rebase_peril]. Много по-малко болезнено би било да публикувате пребазирания клон като нов такъв в GitHub и да отворите нов Pull Request, който сочи към предишния и след това да закриете стария.

Следващият ви въпрос би могъл да е “Как да се обръщам към стар Pull Request?”. Оказва се, че съществуват голям брой начини да се обръщате към други неща почти навсякъде, където можете да пишете в GitHub.

Нека започнем с това как да направим cross-reference към друг Pull Request или Issue. Към всеки Pull Request или Issue се асоциира номер и тези номера са уникални в рамките на проекта. Например, не можете да имате Pull Request #3 и Issue \#3. Ако искате да създадете указател към всеки Pull Request или Issue от кой да е друг такъв, можете просто да въведете \#<num> във всеки ваш коментар или описание. Можете да бъдете и по-специфични, ако Pull Request-ът се намира някъде другаде; напишете username#<num> ако се обръщате към Issue или Pull Request във fork на хранилището, в което се намирате. Или дори username/repo#<num> за да укажете обект от съвсем друго хранилище.

Нека погледнем един пример. Да приемем, че сте пребазирали клона в предишния пример, създали сте нов Pull Request за него и сега искате да посочите стария Pull Request от новия такъв. Също така, искаме да укажем връзка към Issue което се намира във fork на хранилището и в заключение - Issue в съвсем различен проект. Можем да попълним описанието точно както Cross references в Pull Request

Когато изпратим този Pull Request, ще видим всичко това рендерирано като на фигурата Cross references рендерирани в Pull Request.

Забележете, как пълният GitHub URL, който поставихме, е съкратен така че да показва само нужното.

Ако сега Tony се върне и затвори оригиналния Pull Request, ще можем да видим това отбелязано в новия - GitHub автоматично е създал trackback събитие в Pull Request времевата линия. Това означава, че всеки който посети този Pull Request и види, че той е затворен, може лесно да направи връзка с този, който го замества. Линкът ще изглежда по подобен начин като на фигурата Линк към новия Pull Request в линията на времето на затворен Pull Request.

Освен чрез Issue номерата, можете също така да сочите към определен къмит чрез SHA-1 сумата. Трябва да укажете пълните 40 символа и ако GitHub засече това в коментар, ще бъде създаден линк директно към къмита. Отново, можете да сочите към къмити във fork-нати хранилища или към такива в други хранилища по същия начин, по който го правехте с Issues.

Една много интересна възможност, специално за ползване с Pull Request-и, е списъкът със задачи (Task List). По същество това е поредица от чекбоксове, с които да отмятате нещата, които трябва да се свършат. Поставянето им в Issue или Pull Request обикновено индикира, че искате определени задачки да бъдат свършени преди съответния Pull Request/Issue да се приеме като завършен.

Списък се създава така:

Ако въведем подобен код в описание за Pull Request или Issue, ще го видим рендериран като Списък задачи рендериран в Markdown коментар..

Това често се ползва в Pull Request-и за да се укажат нещата, които трябва да се свършат в клона код преди Pull Request-а да бъде одобрен за сливане. Истински готината част е, че можете да натискате чекбоксовете за да обновявате коментара — не е необходимо да редактирате Markdown текста директно за да маркирате задачите като свършени.

В допълнение, GitHub ще претърси вашите Pull Request и Issues за списъци със задачи и ще ги покаже като метаданни на страниците им. Например, ако имате Pull Request със задачи и погледнете overview страницата на всички Pull Request-и, можете да видите до каква степен задачите са изпълнени. Това позволява на потребителите да разделят Pull Request-ите на подзадачи и помага на другите да проследяват развитието на клона. Може да видите пример за това в Преглед на Task list статуса в списъка от Pull Request-и.

Това е особено полезно, когато отворите Pull Request рано във времето и го използвате да за следите как вървят дейностите по имплементация на дадена възможност.

В коментарите можете да добавяте и отрязъци от код. Това е особено полезно, ако искате да представите нещо, което бихте могли да направите преди в действителност да го имплементирате като къмит в клона. Често се използва и за добавяне на примерен код за нещо, което не работи или пък за това какво имплементира дадения Pull Request.

За да добавите част от код в текста, трябва да го “оградите” в обратни апострофи.

Ако добавите и името на езика за програмиране, както сме го направили в примера с 'java', то GitHub също така ще опита да оцвети синтактично отрязъка код. В горния пример, рендерираният текст ще изглежда като Рендериран програмен код

Ако искате да отговорите на малка част от дълъг коментар, можете избирателно да го цитирате слагайки символа > преди редовете. В действителност, това се използва толкова често, че дори съществува клавиатурна комбинация. Ако селектирате текст в коментар, който искате директно да цитирате и натиснете клавиша r, това ще създаде автоматично желания цитат в текстовото поле.

Цитатите изглеждат така:

Веднъж рендериран, коментарът изглежда като Рендериран цитат.

Накрая, можете също така да използвате и emoji. В действителност, тази възможност се ползва доста често в коментарите на Issues и Pull Request-ите като дори съществува emoji helper. Ако пишете коментар и започнете със символа :, то ще се покаже autocompleter за да ви помогне да изберете.

Emoji-тата са под формата на :<name>: навсякъде в коментара. Например, можете да напишете това:

И те ще изглеждат рендерирани като Интензивно ползване на emoji.

Не че emoji-тата са нещо толкова полезно, но добавят елемент на забавление и разведряване в среда, в която това иначе е трудно постижимо.

Чисто технически, това не е част от GitHub Flavored Markdown, но възможността за лесно вмъкване на картинки е полезна функция в GitHub. Вместо да добавяте Markdown линкове към изображения, което може да е доста досадно, сайтът позволява да влачите и пускате изображенията директно в текстовите кутии.

Ако погледнете Вмъквайте изображения директно с Drag and drop и автоматично вграждане, може да видите малката подсказка “Parsed as Markdown” над текстовата област. Щракайки върху нея, можете да видите пълен спомагателен списък на всичко, което можете да правите с Markdown в GitHub.