Návod na práci s CVS projektu OpenOffice.org

Pokud se chcete plnohodnotně podílet na vývoji OpenOffice.org, buď jako překladatel nebo dokonce vývojář kódu, potřebujete mít zřízen přístup do CVS. Použitá metoda je malinko nestandardní, ale je nutná, protože u tak velkého projektu je nutné citlivě řídit přístupová práva k jednotlivým částem kódu.

Přístup do CVS je řízen jednak pomocí autorizace ssh klíčem a jednak jménem a heslem k CVS jako takovému. Jméno a heslo používáte stejné jako pro přístup na portál www.openoffice.org, do IssueZilly a podobně. SSH klíč si vygenerujete podle následujícího návodu.

Návod se zabývá postupem pod operačním systémem GNU/Linux, pod Microsoft Windows jsou principy podobné, nicméně je třeba použít jiné nástroje.

Založení CVS účtu pro OpenOffice.org

1. Pro přístup do CVS projektu OpenOffice.org je nutné mít vygenerován SSH2 klíč. tento klíč si můžete vygenerovat např. pomocí příkazu ssh-keygen -d. Klíč ochráníte heslem, které budete muset zadávat při každém jeho použití, nebo si nakonfigurujete tzv. ssh-agenta a ten bude klíč poskytovat bez potřeby zadávat heslo opakovaně, zadáte jej pouze jednou při nahrání klíče do agenta.
2. Dále je nutné, abyste měl vytvořen účet na serveru www.openoffice.org a tedy byl zaregistrován.
3. Přihlašte se na http://www.openoffice.org, vyberte Issue Tracker -> Enter an Issue, klikněte na cs, Assigned To vyplňte pjanik@openoffice.org, do Summary napište My SSH public key, do Description nějakou hezkou žádost a hlavně své jméno, klikněte na Submit Issue.
4. Klikněte na My Issues a na číslo toho issue, kde najdete Create new attachment, klikněte na Browse (nebo podobně) a z disku vyberte soubor s veřejným klíčem (obvykle ~/.ssh/id_dsa.pub), do Description napište např. "My public key" a zvolte typ "text/plain" a nakonec klikněte na Submit.
5. Počkejte, až vám zařídí klíč. Obvykle to netvá déle než jeden den.

Nyní jste úspěšně prošli první fází a stáváte se plnohodnotným členem týmu projektu OpenOffice.org.

Příprava pracovního prostředí

Vytvoříme si pracovní prostředí. Každý má vlastní názor, jak by mělo vypadat, takže tohle je takové nezávazné doporučení.

Pokud nevíte jak nastavit ssh-agenta, zkuste, zda již není nakonfigurován. Většina moderních distribucí totiž ssh-agenta obsahuje implicitně a jediné co musíte udělat je zkusit zadat příkaz ssh-add. Pokud uvidíte dotaz Enter passphrase for /home/dan/.ssh/id_rsa: máte agenta funkčního a zadáním hesla do něj můžete uploadnout klíč. Zda se vám to povedlo uvidíte podle odpovědi, v případě úspěchu by měla vypadat takto: Identity added: /home/dan/.ssh/id_rsa (/home/dan/.ssh/id_rsa). To vám ušetří mnoho práce v budoucnu. Klíč do agenta je nutné nahrát při každém startu Xserveru.

Dále budeme potřebovat dávku, kterou si vytvoříme tunel na CVS server. Vstoupíme proto do adresáře, kam si dáváme vlastní spustitelné soubory (pravděpodobně ~/bin) a vytvoříme tam nový script jménem ootunnel. Bude mít tento obsah:

#!/bin/bash
ssh -2 -x -L 2401:localhost:2401 tunnel@openoffice.org

jak prosté, jen dva řádky.

Nastavíme si, že script je spustitelný, chmod u+x ootunnel a jdeme dále.

Vytvoříme si v domovském adresáři adresář pro vývoj.

mkdir ~/OOo

a provedeme do něj checkout modulů, které budeme používat. U překladatelů se jedná o modul cs/po. Abysme to mohli udělat, tak potřebujeme mít zaregistrovaný náš ssh klíč na cvs serveru. Tento krok tedy nelze provést před dokončením registrace popsané v první části. Pokud registraci máme, pokračujeme dále:

Otevřeme si xterm, v něm zadáme příkaz

dan@dan:~> ~/bin/ootunnel

Je možné že budeme dotázáni na heslo (passphrase) k privátními ssh klíči. Při prvním spuštění budeme navíc muset akceptovat identitu vzdáleného stroje. Na tuto výzvu je nutné odpovědět "yes", skutečně celým slovem, pouhé Y nefunguje. Pokud je vše v pořádku, dozvíme se:

Tunnel established.  Type ctrl-c to exit.

Otevřeme si další xterm a zadáme:

cd ~/OOo

cvs -d:pserver:moje_jmeno_z_portalu@localhost:/cvs login

.. zadáme heslo, kterým se přihlašujeme na www.openoffice.org

cvs -z3 -d:pserver:moje_jmeno_z_portalu@localhost:/cvs checkout cs/po

cs/po je modul s překlady, pokud budete pracovat na něčem jiném, příslušné jméno modulu Vám sdělí ten, kdo Vás pro danou činnost naverboval.

Nyní jsme dosáhli tzv. checkoutu souborů k překladu či jiným účelům. Ten se provádí jen jednou. Nyní již budeme pokaždé provádět jen cvs up, abychom stáhli do svého adresáře kopie aktuální verze souborů. cvs up se zadává již přímo v adresáři ~/OOo/cs/po nebo v některém z podadresářů.

Každodenní práce s CVS

Každou práci s CVS zahájíme opět spuštěním scriptu ootunnel, jak je popsáno výše.

Když tunel běží, používáme zcela běžné CVS příkazy, tedy pro aktualizaci lokální kopie příkaz cvs up a pro uložení provedených změn do CVS cvs ci.

Po ukončení práce uzavřete tunel stisknutím CTRL+C. Tunel spotřebovává prostředky serveru, proto je vhodné mít jej aktivní jen když jej potřebujete. Tedy u příležitostného uživatele není dobré spouštět je automaticky při každém startu počítače.

Překlady

Nyní si popíšeme jak budeme provádět překlad. Vhodný na to je kbabel, ale použít je možné cokoliv, co umí pracovat s .po soubory. Třeba i textový editor, ale tam je velké riziko chyby. Pokud budeme editovat soubor ručně, tak je nutné před jeho uploadem zkusit příkazem "msgfmt --statistics prekladanysoubor" jestli soubor neobsahuje syntaktickou chybu, která by způsobila chaos při dalším zpracování souborů.

V Kbabelu provedeme následující nastavení:

V menu Projekt-Nový založte nový projekt. Název projektu si vyplňte libovolný, stejně tak Název souboru s nastavením, Jazyk Czech a Typ projektu Jiný. Základní složku PO souborů můžete vyplnit, pokud budete chtít používat Správce katalogů.

Po vytvoření projektu, zvolte Projekt-Nastavit a nastavte:

Identita:
Jméno - vlastní
Plný název jazyka - Czech
kód jazyka - cs
mailling list - dev@cs.openoffice.org

Ukládání:
Kódování UTF8

Různé:
znak klávesových zkratek: ~

a to by mělo z nastavení stačit.

Při příštím spuštění musíte KBabelu říct, že má načíst nastavení tohoto projektu. Buď jej spustíte příkazem kbabel --project cesta/k/souboru/s/nastavením nebo po spuštění KBabelu vyberte Projekt-Načíst.

A můžeme začít překládat.

Když máme daný soubor přeložen zadáme:

EDITOR=joe cvs ci

kde místo joe můžeme zadat jiný oblíbený editor.

Vybafne na nás stránka vypadající nějak takto:

Issue number:
Submitted by:
Reviewed by:
CVS: ----------------------------------------------------------------------
CVS: Issue number:
CVS:   If this change addresses one or more issues,
CVS:   then enter the issue number(s) here.
CVS: Submitted by:
CVS:   If this code has been contributed to the project by someone else; i.e.,
CVS:   they sent us a patch or a set of diffs, then include their name/email
CVS:   address here. If this is your work then delete this line.
CVS: Reviewed by:
CVS:   If we are doing pre-commit code reviews and someone else has
CVS:   reviewed your changes, include their name(s) here.
CVS:   If you have not had it reviewed then delete this line.
CVS: ----------------------------------------------------------------------

a tak pokračuje dále. všechny řádky začínající "CVS:" budou odstraněny, do nich nemá smysl nic psát. Do ostatních je potřeba uvést kdo a proč změny prováděl. Vezmeme to popořadě:

Issue number: ponecháme a doplníme číslo chyby, kterou odstraňujeme, pokud se jedná o chyby hlášenou v IZ. Při běžném překladu ponecháváme nevyplněné.

Submitted by: tento řádek odstraníme, pokud se nejedná o případ, kdy submitujeme překlad, který provedl někdo jiný.

Reviewed by: opět odstraníme, ledaže bysme měli spolupachatele, který náš překlad kontroloval.

Tyto dva řádky jsou určeny spíše pro submity kódu, než překladů.

Na další nový řádek uvedeme důvod, proč děláme commit. Pokud jen tak překládáte, není tam prakticky co napsat. Ale pokud již provádíte revizi nebo opravujete chybu, je velmi důležité tam uvést, co se dělo. Např.

Změna horké klávesy kvůli kolizi

nebo něco podobného, aby bylo vždy vidět, co a jak se se souborem dělo a případně se dalo dohledat, proč akci, která nevypadá logicky, autor dělal.

Po ukončení editace tohoto souboru opustíme editor a uvidíme něco jako:

File /tmp/cvsXtzIe4 saved.
Checking in schedule.po;
/cvs/cs/po/wizards/source/schedule.po,v  <--  schedule.po
new revision: 1.2; previous revision: 1.1
done

Můžeme si gratulovat, náš překlad byl vložen do CVS a při dalším překladu OOo bude automaticky jeho součástí.

Při práci se držte několika zásad:

• Před zahájením překladu oznamte co překládádáte v konferenci vývojářů, aby se nestalo, že budou zbytečně dva dělat totéž. Teoreticky si můžete editovaný soubor v CVS zamknout, ale nepoužíváme to, protože to ani nijak zvlášť dobře nefunguje.

• Vždy než začnete pracovat, udělejte cvs up v adresáři, kde chcete pracovat, máte tak záruku, že začnete s aktuálními soubory. Není tragédie, pokud použijete starší, ale budete mít problémy při commitu a budete muset ručně řešit případné nesoulady.

• Po skončení práce udělejte commit, (cvs ci), nenechávejte to na další den, opět by mohlo dojít ke kolizím.

• Pokud budete updatovat více souborů najednou, nevadí, commit je inteligentní a najde všechny a provede commit najednou. To je výhoda při běžném překladu, kdy nemusíte ten popisný soubor vyplňovat pro každý změněný soubor, ale jen pro všechny najednou. Naopak pokud opravujete chyby hlášené v IZ a mající číslo, dělejte commit po každé změně, aby bylo možné jednoznačně přiřadit opravu k chybě v IZ.

Po skončení práce vstupte do okna, kde jste otevřeli tunel a ukončete jej stiskem Ctrl+C.