Поглавје 7 Контрола на изворниот код со git и GitHub

Во другите поглавја генерално зборуваме за R и разни додатни пакети кои се директно поврзани со повторливи анализи. Овие се алатки се во преден план бидејќи се користат за анализа на податоците или поставување на проекти, но самото развивање на еден истражувачки проект, од идеја до публикација, не е прав, асфалтиран, и осветлен пат. Наспроти, секоја скрипта поминува низ неколку верзии пред конечната (Figure3.2-final-for-print.R), секој извештај започнува како нацрт кој се ревизира од авторот и неколку соработници, многу табели со податоци се ре-форматираат од почеток или заменуваат. Доколку сте работеле на анализа на податоци, и особено ако тоа го правите со соработници, веројатно ви е позната следната ситуација:

sumiraj_trocosi.R
sumiraj_trosoci_po_vraboten.R
sumiraj_trosoci_po_vraboten-2.R
sumiraj_trosoci_final.R
sumiraj_trosoci_juni2020-novo.R
sumiraj_trosoci_juni2020-novo-update.R
...

Веројатно не треба да образложуваме зошто ваквата пролиферација на датотеки е проблематична за вашите анализи, па дури и ако не се стремите кон повторливост. Само замислете како изгледа овој директориум кај некој од вашите колеги кој од една страна има сопствени верзии, а од друга страна нема некои од вашите верзии на истата скрипта. Очигледно е дека можеме и мораме да управуваме со изворниот код далеку подобро. Во ова поглавје ќе се запознаеме со некои од начините со кои git и GitHub ни помагаат да одржуваме работната средина уредена, да соработуваме и експериментираме безгрижно, и да објавуваме ефективно.

7.1 Основи на `git`

Како што напоменавме претходно, git е систем за следење на промените во еден проект, нешто налик на вообичаното track changes во MS Word, но далеку пософистицирано. Учењето на git си бара некое време и трпение, но основите се доволно едноставни да можете веднаш да почнете да користие git. Како и во остатокот од текстот, нашата цел во ова поглавје не е да детален осврт на можностите и особеносите на git (за тоа видете тука), туку да покажеме како git се вклопува во еден повторлив проект и да ве охрабриме до почнете да го користите иако можеби делува комплицирано и застрашувачки.

Еден од најчестите случаи кога ни треба контрола на изворниот код е кога сме стигнале до некоја состојба која фунцкионира или е ставена во употреба (на пример прва верзија од извештајот) и треба да тестираме сугестии од нашите колеги за додавање на нова табела или за поинаков график. Во оваа ситуација, инстинктот кај 99% од нас е да зачуваме копија од оригиналниот извештај кој не сакаме да го изгубиме (можеби во backup-izvestaj) и да ги тестираме предлозите за подобрување во „работна“ верзија на извештајот. Иако во овој момент овој план звучи горе-доле безболно, во пракса скоро никогаш не е така. Наспроти, нашиот уреден директориум со mojizvestaj.Rmd набрзо ќе се претвори во една гужва на датотеки во која што никој, па дури ни ние самите, нема да може да се снајде по неколку недели.

Со git можеме да ја извршиме истата задача но комплетно да ја избегнеме гужвата од датотеки. Задачата „зачувај го оригиналот и чепкај во работна верзија“, концептуално може да се прикаже како едно главно стебло (за оригиналниот извештај кој е веќе во употреба) и една гранка која постои паралелно со главното стебло и во која ние ќе ги тестираме предложените промени.

______1_________ оригинална скрипта (главно стебло)
      \_________ работна верзија (гранка)

1 = разгранување (branch)

Ваквото разгранување на изворниот не е ограничено на една гранка ниту пак на еден корисник: вие и вашите соработници може да развивате безброј паралелни гранки, и дури и да го подобрувате главното стебло истовремено. Во пракса, гранките можеме да ги замислиме како посебни директориуми на нашиот компјутер (кои ги отвараме и менуваме само со git код). Кога сме готови со додавањето содржина, користиме git за да споиме некоја работна гранка во главното стебло:

______1_________ оригинална скрипта (главно стебло) ______2________
      \________ работна верзија (гранка)_________________/
      
1 = разгранување (branch)      
1 = спојување (merge)

Овој концепт со git код може да се претстави вака:

# започни да следиш
git init
# додај и потврди промени
git add + git commit # (N пати)
# направи нова гранка
git checkout -b rabotna-verzija # (1 = разгранување)
# додај и потврди промени во новата гранка 
# (додека главното стебло не се менува)
git add + git commit # (N пати)
# врати се на главното стебло
git checkout main ()
# спои промените од работната верзија во главното стебло
git merge rabotna-verzija # (2 = спојување)
# продолжи да работиш на главнот стебло
git add + git commit (N пати)

Гледаме дека без разлика на која гранка се наоѓаме (во кој скриен директориум работиме) додавањето промени се прави со git add (за да и кажеме на git дека некоја датотека е готова за потврдување ) и git commit (за да ги потврдиме промените). Со секое потврдување (commit), git додава уникатен идентификатор на состојбата во која е таа скрипта (и целиот скриен директориум). Со повикување на овој идентификатор, можеме да се вратиме (назад низ времето) во некоја претходна состојба, на пример пред да додадеме некое парче код кое создава проблем со друга скрипта. Или со гит код:


git add + git commit # id: 1a...
git add + git commit # id: 34...
git add + git commit # id: tt... (прави грешка на друго место)
git add + git commit # id: 01...
git add + git commit # id: ad...
git checkout 34...   # привремено одиме пред да ја додадеме грешката

Кога сме се вратиле на таа претходна состојба, може да отвориме нова гранка, да имплементираме некоја корекција, и кога сме готови, да ги споиме гранките и да се вратиме во состојбата каде што бевме првично.

Не можеме да ја преувеличиме значајноста на совладувањето на ваква или слична процедура во вашето секојдневно програмирање. Безбедноста и флексибилноста на овој систем ве заштитуваат вас и вашите соработници од речиси сите грешки или несреќи во вашата работа (добро, освен умирање на хард дискот).

7.2 Основи на GitHub за соработка и објавување

Употребата на Git за соработка и објавување е олесната благодарение на веб страниците како што се Bitbucket, Github или Gitlab. Се што споменавме до сега се однесуваше на работа во еден репозиториум на нашиот компјутер, до кој нашите соработници немаа директен пристап. Но истиот git репозиториум кој го имаме локално (локална инстанца, local), можеме да го поставиме на GitHub (далечната инстанца, remote). Тогаш, нашите колеги, без разлика каде се, можат да имаат пристап до истата состојба на проектот во која што сме ние. Вашите колеги исто така можат да разгрануваат, спојуваат, итн во нивни посебни гранки кои и вие може да ги гледате, и конечно да побараат од вас како власник на репозиториумот да споите некоја од нивните гранки со главнот стебло (pull request).

Овде ќе се осврнеме на една можност која што ја нуди Github за објавување на статични HMTL документи како едноставни веб страници. Вакви документи, на пример, може да произлезат од повторливи извештаи во Rmarkdown, кои ги конвертираме во HTML (поглавје 5).

Една од гранките кои што се достапни на Github, gh-pages, има специјално значење и функција. Таа автоматски се објавува на интернет доколку се исполнети неколку услови. gh-pages практично овозможува вашиот проект да биде веднаш објавен доколку во вашиот репозиториум има HTML документ кој се наоѓа во посебната папка docs.

Што во пракса значи, дека доколку го составите вашиот извештај со Rmd, и потоа креирате HTML документ кој го зачувувате во docs, поднесувањето на вашиот проект на Github истовремено ќе значи и објавување на една едноставна веб страница. Или чекор, по чекор:

направи корекција на изворниот код во текст едитор
изврши го подобрениот извештај
зачувај го HTML резултатот во docs
додај ги промената и потврди со git
поднеси (git push) до далечната инстанца на репозиториумот (GitHub)
веб страницата на gh-pages ќе биде автоматски корегирана со вашите нови промени

Повторливоста е очигледна. Секој што има пристап до репозиториумот и податоците може да ги следи овие чекори и да ги ре-објави резултатите од анализата како вебсајт. Со вака поставениот проект, ја имаме дополнителната предност, дека доколку сакаме да го ре-извршиме и ре-објавиме извештајот од минатиот Април, со git тоа можеме лесно да го направиме.

Подолу ќе ја разгледаме оваа процедура подетално

7.2.1 Потребен софтвер

За да можете да користите git со rstudio потребно е да инсталирате git од https://git-scm.com/download/win. Исто така потребно е да направите ваша сметка на github.com.

7.2.2 Поставување

Откако ќе креирате сметка на Github, веднаш може да креирате и нов репозиториум. Основните работи што треба да се направат е да се внесе име на репозиторумот и, заради добра пракса, да се креира Readme датотеката.

Поставувања за отварање на нов репозиториум на GitHub

Потоа, во Settngs на репозиторумот поставете ги gh-pages во docs

Поставувања за гранката gh-pages на еден GitHub репозиториум

Потоа во Rstudio креирате нов проект преку File -> New Project -> Version Control, одбирате Git и ги пополнувате генералиите за репозиториумот: URL-то го копирате од Вашиот прелистувач и останатите вредности ги внесувате по желба.

Поставувања за отварање на нов R проект преку постоечки репозиториум на Github

Во следниот чекор Rstudio ќе побара да го внесете корисничкото име и лозинка за Github и ќе ја преземе содржината на репозиториумот. Ако сѐ оди како што треба, во панелот Files во Rstudio би требало да го видите Readme-то што го креиравте претходно.

Сега може да продолжите со работата, како што е опишано во претходните поглавја, за вчитување на податоци, анализа, пишување на Rmarkdown, итн. На крај откако ќе го креирате HTML документот од Rmarkdown, отворете го проектот преку прелистувачот на датотеки, креирајте папка docs и преместете го HTML документот преименувајќи го во index.html.

Во панелот Git во Rstudio сега ќе Ви се појават новите датотеки со жолт прашалник покрај нивното име. Кликнете на Staged за да стане зелено, потоа на Commit и во ново отворениот прозорец внесете порака како на пр. Mojot prv proekt na github. Повторно кликнете на копчето Commit и потоа на зелената стрелка нагоре за Push.

Штом процесот ќе заврши, вашиот изворен код и анализа со податоци ќе биде достапен на github.com/korisnicko_ime/ime_na_repozitorum, a Вашата веб страница на korisnicko_ime.github.io/ime_na_repozitorium/.

Voila, објавивте сѐ одеднаш на интернет.

7.3 Резиме

Дури и без еден едноставен и корисен додаток како gh-pages, кој перфектно се комбинира со повтрорливи Rmd извештаи предностите на овој пристап се очигледни. Сѐ што работите се архивира со соодветни промени и истовремено е достапно за споделување во формат кој што совршено се вклопува на интернет. Недостатоците, или подобро речено, предизвиците, произлегуваат од потребата за совладување на git, што може да бара одредено време, како врпочем и со секој друг голем и повеќенаменски софтверски пакет што се користи од милиони луѓе глобално.