Skip to content

Latest commit

 

History

History
110 lines (61 loc) · 13 KB

pull_requests.md

File metadata and controls

110 lines (61 loc) · 13 KB
Raw

Pull Requests

Pull request се нарича предложение за промяна, което е насочено към дадено хранилище в GitHub. Това е изключително удобен инструмент, чрез който можете да допринесете за усъвършенстването на проект с отворен код (или, в нашия конкретен случай – лекциите на курса, условия на домашни, тестове, код, подобрения по сайта, подобрения по тези ръководства и т.н.).

Инсталация на Git

Тук трябва да отбележим, че ще показваме как се работи с хранилището и със системата за контрол на версии Git, като използваме command-line интерфейса ѝ. Това е основният и най-гъвкав начин да се работи с Git. Друга алтернатива е да си инсталирате графичен клиент. Това е също допустимо, но препоръчваме да го направите само вече ако се чувствате комфортно с конзолните команди и познавате как работи Git.

Windows

За да си инсталирате Git на Windows, е необходимо да свалите и стартирате инсталатора от git-scm.com/download/win. След като го инсталирате можете да го използвате чрез Command Prompt или чрез Git Bash (което ние препоръчваме и се инсталира заедно с Git).

Linux

Инсталацията за Linux е още по-проста. Трябва да отворите терминал и да използвате пакетния мениджър на операционната ви система, в зависимост от дистрибуцията на Linux-a, който използвате. Списък от командите за различните дистрибуции има тук. Може да се наложи да добавите sudo преди съответната команда, ако ви каже, че нямате достатъчно права. Например sudo apt-get install git.

Mac OS

За Mac може да използвате инсталатора на Git. Друга възможност е да си инсталирате homebrew, което е пакетен мениджър за Mac, и чрез него, с brew install git, да инсталирате Git.

Да започваме

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

За да направите pull request, първо трябва да се регистрирате и влезете в GitHub. След като сте готови с това, отваряте страницата на хранилището, към което искате да внесете промени. Лекциите за курса са на този адрес: github.com/fmi/ruby-lectures.

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

Да изтеглим кода

Вече имате fork на хранилището с лекциите. Обаче то се намира само в GitHub. За да си го изтеглите локално, трябва да "клонирате" това ваше копие. Това става като вземете адреса му от URL-a на страницата (на вашия fork) или от текстовото поле в дясната колона, пак на същата страница, и изпълните следната команда в конзолата:

git clone копираният_адрес

В директорията, където сте изпълнили командата, ще се появи поддиректория с името на хранилището.

Да направим branch

Преди да започнете да променяте, направете ново разклонение на кода (branch) чрез:

git checkout -b име

име трябва да е съвсем кратко име от 2 до 4 думи, разделени с тирета, което описва промяната, която ще правите. По конвенция, за хранилището с лекциите, името на branch-a трябва да започва с номера на лекцията, за която се отнася. Тази конвенция – с номера на лекцията в името на branch-а – си е специфично избрана от нас. Например 08-fix-typos.

След като поправите грешката, която сте открили, е хубаво да проверите дали всичко е наред с лекцията. Във файла README.markdown има информация как се компилират лекциите. Компилираните лекции се намират в папката compiled-lectures.

Време е за commit

След като сте приключили с промените, трябва да направите commit.

git commit -a

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

Най-често редакторът, който ще се отвори, е Vim. Ако не сте се сблъсквали с него, може да ви се стори труден за използване. За да се ориентирате, прочетете този кратък и много полезен увод във Vim, написан специално за курса от Андрей Радев.

Добри commit съобщения

Стремете се чрез commit съобщението си, синтезирано, да обясните на този, който ще го чете в бъдеще, каква е промяната и защо сте я направили. Ако се окаже, че няма да се събере в около 60 символа - на първия ред напишете много накратко какво сте променили (например Correct typo in lecture 2), след което оставете един празен ред и отдолу опишете това, което искате да допълните.

Съществува конвенция, която гласи, че commit съобщенията трябва да са в сегашно време, но ако хранилището, към което правите pull request, има друга такава - спазвайте нея. Винаги е полезно да прегледате предишните commit-и и да се придържате към същия стил.

По-подробно указание за добри commit съобщения има написано тук.

Да качим кода

Вече сте почти готови. Направили сте промените, но кодът все още е само на вашия компютър. За да го качите във вашия fork в GitHub, изпълнете следната команда:

git push origin име-на-branch-a

Последна стъпка

Отивате във вашия fork и GitHub ще ви пита дали искате да направите Pull request, защото е видял, че сте направили нов branch. Натискате зеления бутон, попълвате текста и очаквате коментари. :)

Какво се случва сега?

Хората от екипа могат да коментират промените ви, или да ви помолят да направите допълнителни корекции. Когато сме доволни от pull request-a, можем да го merge-нем, тоест да приемем промяната и да я сложим и в нашето хранилище.

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

Ако се наложи да направите промяна по pull request-a, схемата е следната:

  1. Правите промяната локално
  2. git commit -a
  3. git push origin име-на-branch-a

След последната команда промените автоматично ще бъдат отразени в pull request-a.

Ако ви накараме да слеете commit-ите (да ги squash-нете)

Когато има няколко commit-а, които смислово съдържат една промяна, е добре да бъдат следи в един. Терминът за това е "squash". Това става по следния начин:

  1. Изпълнявате git rebase -i master. rebase се използва за промяна на историята на git. Командата ще ви отвори текстов редактор (по подобие на git commit), в който имате списък от commit-и - по един на ред. За всеки, освен първия, трябва да промените думата pick на squash. Това, което ще се случи е, че промените от commit-ите ще бъдат слети в един. В екраните, които ще виждате, има доста коментари, които обясняват кавко се случва и дават инструкции какво да правите. Четете ги.
  2. git push -f origin име-на-branch-a Забележете флага -f. Той позволява на git да презапише старите ви commit-и с новия.

Ако fork-ът ви е стар в сравнение с fork-натото хранилище

Ако в оригиналното хранилище, което сте fork-нали, бъдат направиени промени след момента на fork, вашето копие (fork) трябва да се обнови, за да включва въпросните нови промени. Това става по следния начин:

  1. git fetch upstream - ако се получи грешка, че нямате upstream, тогава преминете на стъпка 1.1, иначе на стъпка 2.
  2. git remote -v - ще покаже добавените в текущото ви хранилище (fork) отдалечени копия.
  3. git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git
  4. git remote -v - ще видите, че вече има upstream хранилище, т.е. хранилището, което сте fork-нали.
  5. git rebase upstream/master - Тази команда ще вземе новите промени от master branch-а на upstream хранилището, ще ги сложи във вашия feature branch и след това ще приложи върху тях вече направените от вас нови commit-и. Резултатът ще е все едно сте направили промените си върху последната версия на upstream/master, а не върху по-стара такава.
  6. git push -f origin име-на-branch-a - това ще качи commit-ите ви, приложени върху последната версия на upstream/master, във вашето хранилище. С тази операция GitHub автоматично ще обнови и pull request-а, който сте пуснали, от име-на-branch-a във вашия fork, към upstream/master. Тук флагът -f прави force push. Това е необходимо заради rebase командата, извършена в стъпка 2, която реално пренаписва историята.

Очакваме pull request-и!