Chapters ▾ 2nd Edition

4.3 GitHub - Управление на проект

Управление на проект

След като вече сме готови да сътрудничим в проекти на други хора, ще погледнем и обратната страна: създаване, поддържане и администриране на собствен проект.

Създаване на хранилище

Нека създадем ново хранилище, чийто код да споделим с другите. Започваме натискайки бутона “New repository” в дясната част на екрана или натискайки бутона + в горния тулбар до потребителското ни име както можем да видим в Падащият списък “New repository”.

Частта “Your repositories”
Фигура 109. Частта “Your repositories”
Падащият списък “New repository”
Фигура 110. Падащият списък “New repository”

Това ни прехвърля към формата “new repository”:

Формата “new repository”
Фигура 111. Формата “new repository”

На практика, единственото задължително поле е това с името на проекта, всички останали са незадължителни. Засега просто натиснете бутона “Create Repository” и вече разполагате с ново хранилище в GitHub, с име <user>/<project_name>.

Понеже все още нямате качен никакъв код, GitHub ще ви предложи инструкции как да създадете ново Git хранилище или да се свържете със съществуващ Git проект. Няма да навлизаме в детайли за това, ако имате нужда от припомняне, погледнете Основи на Git.

Сега проектът ви се хоства в GitHub и можете да изпратите URL-а на всеки, с който желаете да го споделите. Всеки GitHub проект е достъпен през HTTPS като https://github.com/<user>/<project_name>, а също и през SSH като git@github.com:<user>/<project_name>. Git може да тегли и да изпраща и по двата начина, а достъпът се контролира с правата на името и паролата на свързващия се потребител.

Забележка

Често се предпочита HTTPS-базиран достъп, понеже по този начин външният потребител може да клонира проект и без да има GitHub акаунт. Ако някой потребител предпочита SSH достъп, то той трябва да има акаунт и качен SSH ключ. HTTPS адресът е същият, който потребителят би написал в браузъра си за уеб базиран достъп до проекта.

Добавяне на сътрудници

Ако работите с други хора по проекта си и желаете да им дадете възможност да правят къмити, трябва да ги добавите към проекта като “collaborators”. Ако Ben, Jeff, и Louise имат GitHub акаунти и искате да има дадете Push достъп до вашето хранилище, можете да ги добавите към проекта, така че да могат както да четат, така и да пишат в кода.

Натиснете линка “Settings” в дъното на дясната част.

Препратката settings за хранилището
Фигура 112. Препратката settings за хранилището

След това, изберете “Collaborators” от менюто вляво. Въведете потребителското име, което желаете и щракнете"`Add collaborator.`" Можете да повторите това за колкото други потребителя желаете. Ако искате пък да отнемете достъпа, просто щракнете “X” иконата в дясната част на съответния ред.

Сътрудници в хранилище
Фигура 113. Сътрудници в хранилище

Управление на Pull Requests

Сега вече имате проект с код в него и може би няколко сътрудника с push достъп до хранилището - нека да видим какво да направите, когато получите Pull Request.

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

За тези примери, нека приемем, че вие сте потребител “tonychacon” и сте създали нов Arduino проект наречен “fade”.

Email известяване

Някой се появява, променя част от кода ви и ви изпраща Pull Request. Ще получите електронна поща за новия Pull Request изглеждащ подобно на Email известяване за нов Pull Request.

Email известяване за нов Pull Request
Фигура 114. Email известяване за нов Pull Request

Няколко неща са за отбелязване в този имейл. Първо, той съдържа малък diffstat — списък на файловете, в които има промени от Pull Request-а и в какво количество са те. След това, имате линк към Pull Request-а в GitHub. Предоставят ви се и няколко URL-а, които можете да ползвате от командния ред.

Ако виждате ред git pull <url> patch-1, това е прост начин да слеете отдалечен клон без да трябва да добавяте remote. Видяхме това в Извличане от отделечени клонове. Ако искате, можете да създадете и да превключите в topic клон и след това да изпълните тази команда за да слеете Pull Request-а.

Другите интересни URL-и са .diff и .patch URL-ите, които както можете да предположите, осигуряват unified diff и patch версии на Pull Request-а. Технически, можете да слеете работата в Pull Request-а примерно така:

$ curl https://github.com/tonychacon/fade/pull/1.patch | git am

Съвместна работа по Pull Request

Както видяхме в Работния процес в GitHub, сега можете да проведете дискусия с човека, който е пуснал Pull Request-а. Можете да коментирате специфични редове код, да коментирате цели къмити или целия Pull Request, използвайки GitHub Flavored Markdown където искате.

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

Отговор по Email
Фигура 115. Отговорите на имейлите се показват в нишката

Веднъж след като кодът е одобрен и искате да го слеете, можете или да го издърпате и слеете локално с помощта на git pull <url> <branch> синтаксиса, който видяхме по-рано, или да добавите fork-хранилището като remote, да го изтеглите и слеете.

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

Merge бутон
Фигура 116. Merge бутон и инструкции за сливането на Pull Request-а ръчно

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

Pull Request референции

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

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

За да демонстрираме това, ще използваме low-level команда (често наричана “plumbing” команда, за която ще научим повече в Plumbing и Porcelain команди) наречена ls-remote. Обикновено тази команда не се използва ежедневно в Git операциите, но е полезна защото ни показва какви референции съществуват на сървъра.

Ако стартираме тази команда за “blink” хранилището, което ползвахме по-рано, ще видим списък от всички клонове, тагове и други референции в него.

$ git ls-remote https://github.com/schacon/blink
10d539600d86723087810ec636870a504f4fee4d	HEAD
10d539600d86723087810ec636870a504f4fee4d	refs/heads/master
6a83107c62950be9453aac297bb0193fd743cd6e	refs/pull/1/head
afe83c2d1a70674c9505cc1d8b7d380d5e076ed3	refs/pull/1/merge
3c8d735ee16296c242be7a9742ebfbc2665adec1	refs/pull/2/head
15c9f4f80973a2758462ab2066b6ad9fe8dcf03d	refs/pull/2/merge
a5a7751a33b7e86c5e9bb07b26001bb17d775d1a	refs/pull/4/head
31a45fc257e8433c8d8804e3e848cf61c9d3166c	refs/pull/4/merge

Разбира се, ако сте във вашето хранилище и изпълните git ls-remote origin или кой да е друг remote, ще видите отпечатан изход подобен на този.

Ако хранилището е в GitHub и имате отворени Pull Request-и, ще получите тези референции с префикс refs/pull/. Това по същество са клонове, но понеже не са под refs/heads/, нормално не ги получавате когато клонирате или изтегляте от сървъра — fetching процесът по подразбиране ги игнорира.

Има по две референции на Pull Request - едната която завършва на /head сочи към точно същия къмит както и последния къмит в Pull Request клона. По този начин, ако някой отвори Pull Request в наше хранилище и клонът му се казва bug-fix, сочещ към къмит a5a775, тогава в нашето хранилище ние няма да имаме bug-fix клон (той е във fork-а), но ще имаме pull/<pr#>/head референция сочеща към a5a775. Това означава, че можем лесно да изтеглим всеки Pull Request клон в една стъпка без да трябва да добавяме множество remotes.

Сега можем да изтеглим референцията директно.

$ git fetch origin refs/pull/958/head
From https://github.com/libgit2/libgit2
 * branch            refs/pull/958/head -> FETCH_HEAD

Това инструктира Git да се свърже с origin адреса и да изтегли референцията наречена refs/pull/958/head. Git за щастие следва инструкцията и сваля всичко необходимо за конструирането на тази референция, след което поставя указател към къмита, който искате в .git/FETCH_HEAD. Можете да продължите с git merge FETCH_HEAD в клон, в който да тествате, но merge commit съобщението изглежда леко странно. Също така, ако разглеждате много Pull Request-и, това става досадно

Съществува също начин да изтеглите всички Pull Request-и и да ги актуализирате всеки път, когато се свързвате с отдалечения сървър. Отворете файла .git/config и потърсете origin секцията. Ще изглежда по подобен начин:

[remote "origin"]
    url = https://github.com/libgit2/libgit2
    fetch = +refs/heads/*:refs/remotes/origin/*

Редът , който започва с fetch = се нарича “refspec.” Това е начин за съотнасяне на имена в сървъра с имена в локалната ви .git директория. В примера тук, това казва на Git, "нещата на сървъра, които се намират в refs/heads трябва да се съхраняват в локалното ми хранилище в refs/remotes/origin." Можете да промените тази секция за да добавите друг refspec:

[remote "origin"]
    url = https://github.com/libgit2/libgit2.git
    fetch = +refs/heads/*:refs/remotes/origin/*
    fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

Това инструктира Git че, “всички refs изглеждащи като refs/pull/123/head трябва да се съхраняват локално като refs/remotes/origin/pr/123.” Сега, ако запишете файла и изпълните git fetch:

$ git fetch
# …
 * [new ref]         refs/pull/1/head -> origin/pr/1
 * [new ref]         refs/pull/2/head -> origin/pr/2
 * [new ref]         refs/pull/4/head -> origin/pr/4
# …

Сега всички отдалечени Pull Request-и се представят локално като refs, които работят като tracking клонове - те са само за четене и се обновяват когато теглите. Това прави много лесно изпробването на код от Pull Request локално:

$ git checkout pr/2
Checking out files: 100% (3769/3769), done.
Branch pr/2 set up to track remote branch pr/2 from origin.
Switched to a new branch 'pr/2'

Наблюдателните читатели ще забележат надписа head в края на remote частта на refspec. Съществува също и refs/pull/#/merge референция от страна на GitHub, която представлява къмита, който ще се създаде ако натиснете бутона “merge” в сайта. Това може да ви позволи да тествате сливането преди още да сте натиснали бутона.

Pull Requests на Pull Requests

Можете да създавате Pull Request-и насочени не само към главния (master) клон, а към всеки един клон в мрежата. В действителност, можете да ги насочите и към друг Pull Request.

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

Когато започвате да правите Pull Request, в горната част на екрана има кутия, указваща от и към кой клон опитвате да го насочите. Ако натиснете бутона “Edit” вдясно от кутията, можете да смените не само клоновете, но и fork-а.

PR targets
Фигура 117. Ръчна смяна на целевия клон и fork на Pull Request

Тук можете сравнително лесно да слеете вашия нов клон в друг Pull Request или друг fork на проекта.

Бележки и уведомления

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

Във всеки коментар, можете да въведете символа @ и ще получите autocomplete списък с имената и потребителските имена на сътрудниците в проекта.

Mentions
Фигура 118. Въведете @ за да упоменете някого

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

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

Ако някой е бил упоменат в Pull Request или Issue, той ще бъде “абониран” към тях и ще бъде осведомяван своевременно за възникнала активност. Ще бъдете абонирани също така за всичко, което сте стартирали, за събития в наблюдавани хранилища или когато коментирате нещо. Ако не желаете да получавате нотификации, в съответната страница има бутон “Unsubscribe”, с който да се отпишете от уведомяванията свързани с нея.

Unsubscribe
Фигура 119. Отписване от нотификации за Issue или Pull Request

Страницата за уведомления

Под “нотификации” в смисъла на GitHub имаме предвид специфичния подход, който сайтът използва за да поддържа връзка с вас при възникнали събития. Съществуват няколко различни начина за тяхната настройка. Ако отворите секцията “Notification center” от страницата с настройки можете да видите част от наличните опции.

Опции за известяване
Фигура 120. Опции за известяване

Двата избора за получаване на известия са през “Email” и “Web” и може да изберете кой да е от двата, двата едновременно или пък нито един

Web известяване

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

Център за известия
Фигура 121. Център за известия

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

Всички тези инструменти са полезни при работа с голям брой известия. Много от опитните GitHub потребители изключват изцяло имейл уведомленията и управляват известията си през този екран.

Email известяване

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

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

Например, ако разгледаме хедърите на писмото до Tony показано в Email известяване за нов Pull Request, ще забележим следното: