Git
Chapters ▾ 2nd Edition

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

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

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

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

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

Частта ``Your repositories''.
Figure 110. Частта “Your repositories”.
Падащият списък ``New repository''.
Figure 111. Падащият списък “New repository”.

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

Формата ``new repository''.
Figure 112. Формата “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 може да тегли и да изпраща и по двата начина, а достъпът се контролира с правата на името и паролата на свързващия се потребител.

Note

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

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

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

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

Препратката settings за хранилището.
Figure 113. Препратката settings за хранилището.

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

Сътрудници в хранилище.
Figure 114. Сътрудници в хранилище.

Управление на 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
Figure 115. 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
Figure 116. Отговорите на имейлите се показват в нишката.

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

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

Merge бутон
Figure 117. 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
Figure 118. Ръчна смяна на целевия клон и fork на Pull Request.

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

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

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

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

Mentions
Figure 119. Въведете @ за да упоменете някого

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

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

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

Unsubscribe
Figure 120. Отписване от нотификации за Issue или Pull Request.

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

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

Опции за известяване
Figure 121. Опции за известяване.

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

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

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

Център за известия
Figure 122. Център за известия.

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

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

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

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

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

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

To: tonychacon/fade <fade@noreply.github.com>
Message-ID: <tonychacon/fade/pull/1@github.com>
Subject: [fade] Wait longer to see the dimming effect better (#1)
X-GitHub-Recipient: tonychacon
List-ID: tonychacon/fade <fade.tonychacon.github.com>
List-Archive: https://github.com/tonychacon/fade
List-Post: <mailto:reply+i-4XXX@reply.github.com>
List-Unsubscribe: <mailto:unsub+i-XXX@reply.github.com>,...
X-GitHub-Recipient-Address: tchacon@example.com

Тук има няколко интересни неща. Ако искате да осветите или препратите имейлите от този конкретен проект или дори Pull Request, информацията в хедъра Message-ID ви дава всички данни във формата <user>/<project>/<type>/<id>. Ако например пощата се отнася до даден Issue, тогава <type> полето ще е “issues” вместо “pull”.

List-Post и List-Unsubscribe хедърите помагат на съвместимите имейл клиенти бързо да изпратят отговор или да се отпишат от дискусията. По същество ефектът е същия както ако натиснете “mute” бутона в сайта или “Unsubscribe” в Issue или Pull Request страница.

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

Специални файлове

Съществуват няколко специални файла, които GitHub ще забележи, ако присъстват в хранилището ви.

README

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

Много екипи ползват това за представяне на най-важните аспекти от проекта пред незапознатите с него потребители. Това би могло да включва:

  • Каква е целта на проекта

  • Как се конфигурира и инсталира

  • Пример за това как се ползва и пуска

  • Лицензът, под който се публикува

  • Указания за сътрудничество в него

Понеже GitHub рендерира този файл, можете да вмъквате линкове (вкл. и към изображения) за допълнително улеснение на разглеждащия.

CONTRIBUTING

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

Contributing notice
Figure 123. Създаване на Pull Request при наличен CONTRIBUTING файл.

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

Администриране на проект

В общи линии броят на административните действия за единичен проект не е голям, но има няколко интересни опции.

Смяна на клона по подразбиране

Ако ползвате име на клон по подразбиране различно от “master” за основния клон, можете да укажете това в секцията “Options” в страницата с настройки за хранилището.

Клон по подразбиране
Figure 124. Смяна на клона по подразбиране за проект.

Просто сменете клона по подразбиране от падащия списък и той ще стане такъв за всички главни действия занапред, включително за това от кой клон ще се извлекат файловете на проекта когато някой клонира хранилището.

Трансфер на проект

Ако искате да прехвърлите проекта си към друг потребител или организация в GitHub, разполагате с опция “Transfer ownership” в долната част на същата “Options” секция от настройките на проекта.

Прехвърляне на проект
Figure 125. Трансфер на проект към друг GitHub потребител или организация.

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

Това не само ще премести хранилището заедно с всичката информация за него към друго място, но също така и ще бъде създаден redirect URL към новото място. Клониранията и изтеглянията от Git също ще бъдат пренасочени, а не само за уеб заявките.