OpenOffice.cz - web věnovaný kancelářským balíkům OpenOffice.org

Commit změny

Změny zdrojového souboru máme hotovy, dosud jsme je ale nezaznamenali jako commit, tedy změnu, jak ji chápe systém pro správu verzí. Commit by se měl týkat určitého tématu a neměnit nic, co s ním nesouvisí (což naše změna splňuje). Před commitnutím nesmíme zapomenout změny prohlédnout a zkontrolovat:

git status # seznam změněných souborů
git diff # výpisy změn v souborech

Přehled změn od posledního commitu v rozhraní git-cola

Jsme-li se změnami spokojeni, použijeme kouzelný příkaz:

git commit -a

Otevře se textový editor, ve kterém napíšeme na první řádek shrnutí změn. Představu o něm si můžeme udělat podle ostatních commitů, zpravidla začíná typem provedené změny v rozkazovacím způsobu (například add, remove, update). Týká-li se změna chyby v bugzille, je žádoucí kvůli vzájemné provázanosti začít shrnutí kódem fdo# následovaným číslem chyby (tyto kódy budou ještě popsány v díle o hlášení chyb). Řádků s vysvětlením commitu může být víc, mezi prvním a druhým je však třeba v editoru jeden řádek vynechat.

U každého commitu je uveden autor a jeho e-mail, aby bylo zřejmé, na koho se můžeme v souvislosti s daným kusem kódu obrátit. Tyto údaje se nezadávají při commitu, ale automaticky se přebírají ze souboru .gitconfig, kam je třeba je před prvním commitem uložit.

V našem příkladu bude dostatečným shrnutím věta „add comments in margins option to PDF export“. O tom, že byl commit úspěšně zadán, se lze přesvědčit ve výpisu commitů (příkaz git log).

Gerrit a nastavení propojení

Pokud bychom měli oprávnění, jaká mají zasloužilí vývojáři LibreOffice, mohli bychom commit vložit také do originálního repozitáře na freedesktop.org. Poněvadž tomu tak není, musí se na naši změnu (jež se v podobě textu se změnami označuje jako patch) někdo z vývojářů podívat, schválit ji a poslat do originálního repozitáře. K těmto revizím patchů slouží v projektu LibreOffice nástroj Gerrit.

Gerrit umožňuje pohodlně posuzovat změny ve zdrojovém kódu. Díky propojení s repozitáři se do Gerritu posílají patche přímo prostřednictvím systému pro správu verzí, po schválení se pak automaticky začlení do originálního repozitáře. Gerrit pro LibreOffice se nachází na gerrit.libreoffice.org. U každého patche nalezneme přehled všech jeho verzí (patch se může měnit podle připomínek) a komentáře revidujících vývojářů. Ke schválení do větve master je potřeba souhlas aspoň jednoho vývojáře s příslušným oprávněním, pro větve konkrétních verzí je zapotřebí souhlasů více (aby se omezilo riziko začlenění chyby).

Nastavení toho, aby lokální repozitář s Gerritem spolupracoval, je podrobně popsáno na wiki a shrnuto na následujících řádcích:

Budeme potřebovat uživatelský účet na webu Gerritu (přihlásit se lze i pomocí OpenID nebo účtu u Googlu), kde si zvolíme uživatelské jméno a vyplníme celé jméno a e-mailovou adresu.

Při přijímání patchů Gerritem se ověřuje totožnost autora pomocí SSH klíče. Nastavení klíčů je popsáno v návodu na Githubu. Pokud klíče doposud nemáme, napřed je vytvoříme a při tom zvolíme heslo, které bude vyžadováno při odeslání commitu. Poté vložíme do nastavení účtu na webu Gerritu veřejný klíč ze souboru ~/.ssh/id_rsa.pub.

Dalším krokem je doplnění nastavení pro Gerrit do konfiguračního souboru ~/.ssh/config. Příslušné řádky jsou součástí návodu na wiki.

Následně nastavíme, že za vzdálený repozitář Gitu bude považován Gerrit. Přejdeme do adresáře s lokální kopií repozitáře help a zadáme:

git config remote.origin.pushurl ssh://logerrit/help

S tímto nastavením bychom už commity úspěšně odesílali, Gerritem by však nebyly přijaty. Každý commit pro Gerrit totiž musí na posledním řádku shrnutí změn obsahovat identifikátor (díky němu můžeme patch vylepšovat, aniž by se v Gerritu objevil jako nový). Přidávání identifikátoru zajistíme tím, že do repozitáře Gitu přidáme tzv. hook, činnost, která se bude při každém commitu automaticky provádět (uzivatel je uživatelské jméno zadané na webu Gerritu):

scp -p -P 29418 uzivatel@gerritlibreofficeorg:hooks/commit-msg .git/hooks/

Odeslání změny do Gerritu

Se správně nastaveným propojením je už odeslání změny do Gerritu snadné a může vypadat následovně:

git checkout master # aktualizujeme repozitář
git pull # stáhneme do něj nové změny

Pro každou změnu je vhodné vytvořit větev, můžeme tak pracovat na více změnách zároveň, aniž bychom čekali na jejich schválení.

git checkout -b sezmenou # vytvoření větve nazvané „sezmenou“

Následně změníme zdrojové soubory…

git commit -a # …a změny commitneme

Přichází krása toho všeho, změny mezi naší větví a vzdáleným repozitářem pošleme do Gerritu:

git push origin sezmenou:refs/for/master

Budeme při tom vyzváni k zadání hesla ke svému klíči.

Pokud na základě komentářů ostatních změnu v lokálním repozitáři upravíme, upravíme i commit pomocí:

git commit -a –-amend

Jelikož identifikátor commitu zůstane stejný, při opětovném odeslání do Gerritu se nový patch automaticky přiřadí k předešlým.

Až bude patch přijat, zbývá smazat naši již nepotřebnou větev:

git checkout master # přepneme se z naší větve zpátky na master
git branch -D sezmenou # větev smažeme

Přes Gerrit byla odeslána i ukázka s doplněním nápovědy k exportu komentářů, a najdeme v něm tedy o ní záznam. Z něj vyčteme, že po třech dnech byla změna bez připomínek schválena a začleněna do větve master. Od té doby ji můžeme najít také ve webovém rozhraní k hlavnímu repozitáři. Během několika dní tak byla nesrovnalost, které jsme si všimli, opravena. A to je hlavní rozdíl a velká výhoda v porovnání s tím, když bychom návrh na doplnění pouze nahlásili do bugzilly – na hlášení může bez odezvy jen dlouhá léta sedat prach.

Jakožto autory by nás mohla zajímat případná odezva na změnu, třeba zda se v novém textu najdou nejasnosti, které revize neodhalila. Uživatel by zřejmě vyplnil hlášení v bugzille, pravděpodobnější ale je, že se ozve někdo z překladatelů. Novinky z nápovědy se totiž časem dostanou do Pootlu a také naše dílo bude přeloženo do desítek jazyků. Někteří překladatelé bývají tvorové správně kritičtí a objevené nesrovnalosti v překládaných řetězcích hlásí na lokalizační konferenci (seznámili jsme se s ní v prvním díle seriálu).

Poněvadž větev libreoffice-4-3 byla vytvořena z větve master až poté, co byla naše změna začleněna, obsahovala ji už od začátku. Povedlo se nám tak nápovědu LibreOffice verze 4.3 obohatit o jeden řádek, a ačkoliv celé úsilí trvalo tři díly seriálu, s připraveným zázemím se jedná o záležitost v řádu minut.

Doplněná, dosud nepřeložená část nápovědy v beta verzi LibreOffice 4.3

Prohlášení o licenci a vývojářská konference

Pokud se jedná o náš první příspěvek do kódu LibreOffice – bez ohledu na to, zda se jedná o nápovědu, i ta je součástí repozitáře – musíme učinit zadost licenčním záležitostem. Stačí poslat do vývojářské konference e-mail s prohlášením, že všechny naše příspěvky do projektu LibreOffice včetně budoucích mohou být licencovány pod dvojicí licencí Mozilla Public License a GNU Lesser General Public License (ukázka licenčního prohlášení), a přidat se na wiki stránku se seznamem vývojářů (kvůli tomu je nutné mít na wiki TDF účet).

Vývojářská konference LibreOffice má adresu libreoffice@listsfreedesktoporg (její archiv). Slouží výhradně k diskuzi týkající se vývoje obecně či k radám vztahujícím se ke zdrojovému kódu, také na ni automaticky přichází přehledy aktivity u vybraných chyb. Zasílání patchů a diskuze k nim byla přesunuta na Gerrit. O konkrétních nahlášených problémech vývojáři diskutují v příslušných záznamech bugzilly. Vývojářská konference není určena tazatelům, kteří nehodlají upravovat zdrojový kód.

Dalším místem určeným k diskuzím vývojářů je IRC místnost #libreoffice-dev na Freenode (webové rozhraní).

Budoucnost nápovědy

Možná jste z předcházejících odstavců a kapitol nabyli dojmu, že proces tvorby nápovědy je nepřehledný, složitý a vyžaduje dovednosti, které by po uživatelích a tvůrcích dokumentace nikdo neměl chtít. V tomto případě se nejedná o dojem, ale o realitu – je zřejmé, že systém nápovědy psané programátory neobstojí v situaci, kdy ji má tvořit komunita, a značně přispívá k tomu, že se nápovědou téměř nikdo nezabývá.

Neutěšeného stavu si jsou vývojáři vědomi. Od vzniku LibreOffice je dlouhodobým záměrem systém nápovědy zcela přepracovat: v současné online verzi, která je ve formě wiki stránek (nyní pouze pro čtení), by bylo možné text okamžitě upravovat, přičemž by se změny promítly i do offline verze. Tento úkol je komplikovaný, je nutné například zachovat stávající funkcionalitu offline verze nebo zajistit možnost překladů a zachovat všechny stávající překlady. Snad se v dohledné době nové verze dočkáme – byla by velkou šancí nápovědu zachovat při životě. Jinými slovy, nápověda před sebou bude mít světlejší budoucnost ve chvíli, kdy se tento a předchozí díl seriálu budou moci smazat jakožto neaktuální.

Pokračování příště

Je načase nápovědu opustit, další díl popíše několik zbylých témat týkajících se dokumentace. Zmíníme se o tom, jakou další uživatelskou dokumentaci projekt LibreOffice nabízí a jak přispět k jejímu překladu do češtiny.