XIQE/Guide

Z FI WIKI
Přejít na: navigace, hledání

Zpět na XIQE

Naposledy aktualizováno: --Petr Vlček 19:42, 26. 4. 2006 (CEST)

XIQE Developer's Guide

Infrastruktura

Wiki

Projekt má dvě wiki, českou a anglickou. Česká wiki je tato a slouží pro české vývojáře převážně z řad studentů Fakulty informatiky Masarykovy univerzity v Brně. Anglická wiki je oficiální a je integrovaná s evidencí chyb a požadavků (issue tracking), s prohlížečem repozitory zdrojových kódů a se sledováním změn. Na rozdíl od off-line reportů generovaných nástrojem Maven jsou všechna data aktuální.

Pracovní diskuse v češtině se vedou zde, nicméně dokumenty a informace, které by mohly zajímat ostatní vývojáře, by se měly umisťovat do oficiální wiki (samozřejmě v angličtině). Anglická wiki by měla spolu se stránkami generovanými nástrojem Maven sloužit k prezentaci informací o projektu potenciálním zájemcům a vývojářům.

SVN repository

Subversion repository je přístupné na adrese https://www.bilysklep.cz/repos/xml/trunk/xiqe/.

Konference

Projekt XIQE má dvě e-mailové konference.

  • Konference xiqe slouží ke komunikaci členů týmu a ke svolávání schůzek. Pokud ještě nejste do této konference přihlášeni, můžete tak učinit na adrese http://www.xiqe.org/mailman/listinfo/xiqe. Příspěvky do konference posílejte na e-mailovou adresu xiqe@xiqe.org.
  • Do konference xiqe-monitor se zasílají zasílány zprávy o aktivitě v projektu (momentálně zasílají především informace o ticketech a jejich změnách, v budoucnu se budou zasílat i zprávy o commitech do repozitory). Přihlásit se můžete na adrese http://www.xiqe.org/mailman/listinfo/xiqe-monitor. Do této konference zprávy neposílejte, slouží pouze pro automaticky generované zprávy.

Trac

Trac je sada vzájemně integrovaných nástrojů pro efektivní řízení projektů. Na jednom místě tak lze využít wiki, on-line prohlížeč repository a systém oznamování a evidenci chyb.

Timeline

Timeline poskytuje čerstvé informace o dění v projektu. Pod uvedeným odkazem najdete chronologický přehled posledních změn repository, změny v issue tracking systému a změny stránek wiki.

Code Browser

Systém Trac obsahuje zdařilý prohlížeč zdrojových kódů v repository. Prohlížeč umožňuje procházet libovolnou revizi v historii. Jednotlivé commity jsou zde označeny jako changeset.

Changeset poskytuje vyčerpávající informace o jednotlivých commitech včetně přehledu změněných souborů a přehledného zobrazení rozdílů mezi zvolenou a předchozí revizí (diff).

Issue Tracking

Issue tracking (někdy také bug tracking) je označení pro systémy usnadňující odstraňování chyb (nejen) v software. Typické issue tracking systémy umožňují jednoduché vytváření a evidenci záznamů o chybách, vyhledávání v takto vzniké databázi chyb, přiřazování priorit a závažnosti jednotlivým záznamům a možnost definovat toky práce (určení osob odpovědných za odstranění chyby).

S dobrým nástrojem pro evidenci chyb se lze při řízení projektu vyvarovat takových chyb, jako je řešení problémů ve špatném pořadí priorit nebo úplné opomenutí problému.

Záznam o chybě se v terminologii Tracu označuje jako ticket. Pro začátek jsou definovány tři typy ticketů:

  • Defect — nejběžnější typ, ticket typu defect se používá pro oznámení nalezení chyby v programu.
  • Task — tento typ se používá pro zadání úkolu.
  • Enhancement — tento typ se používá pro vložení požadavku na vylepšení nebo přidání nových funkcí.

Hlavním obsahem ticketu je krátké shrnutí problému a jeho detailní popis. Každý ticket má množinu atributů s následujícím významem:

  • Reporter — Identifikace odesílajícího (viz. Přihlašovací údaje).
  • Component — Modul nebo subsystém, kterého se ticket týká.
  • Version — Verze, ve které byla nalezena chyba, resp. verze, které se týká úkol nebo požadavek.
  • Milestone — Nejpozdější datum, do kterého má být problém vyřešen.
  • Keywords — Klíčová slova pro vyhledávání.
  • Priority — Jak rychle má být problém vyřešen (s jakou prioritou).
  • Severity — Závažnost problému.
  • Assigned to/Owner — Login osoby odpovědné za vyřešení problému.
  • Cc — E-mailová adresa nebo login osoby, které mají být zasílány kopie oznamovacího e-mailu při vložení a změnách ticketu.
  • Resolution — Důvod uzavření ticketu (problém vyřešen, špatný požadavek, duplikát ticketu, ...).
  • Status — Status ticketu (Nový, Přiřazený/Znovuotevřený, Uzavřený).

Vybrané atributy ticketů mohou v Tracu systému XIQE měnit pouze přihlášené osoby. Vkládat nové tickety a přidávat komentáře k existujícím ticketům mohou všichni uživatelé systému, včetně anonymních.

Pokud budete vkládat nový ticket, uveďte, z důvodů snadné identifikace, svůj login do pole reporter. Pokud se před vložením ticketu přihlásíte, systém váš login vloží do pole automaticky. Stejná identifikace se používá i v poli Assigned to/Owner.

Wiki

Wiki je v systému Trac integrováno tak těsně, že jeho formátování můžete použít téměř všude, kde vkládáte nějaká data. Můžete tak vzájemně odkazovat na stránky wiki, revize v repository, commity (changeset) a hlášení chyb (ticket).

Při editaci mějte na vědomí, že syntaxe wiki v systému Trac je odlišná od syntaxe MediaWiki, kterou jste zvyklí používat na kore.

Jednou ze stěžejních funkcí wiki v systému trac je funkce TracLinks, umožňující odkazovat v rámci textu na jednotlivé tickety, revize, changesety, atd.

Přihlašovací údaje

Téměř všechny funkce systému Trac, až na pár výjimek, jsou přístupné všem anonymním uživatelům. Mezi omezené funkce patří například rozšířená editace ticketů.

Pro přihlášení použijte jméno a heslo, které používáte pro přístup do Subversion repository.

Pokud se přihlašujete poprvé, navštivte ještě odkaz Settings a nastavte si zde své jméno a e-mail (nebude se nikde zobrazovat). Po nastavení můžete pro identifikaci v ticketech používat už jen svůj login.

Konvence

Komentáře

Veškerý kód by měl být opatřen komentáři Javadoc v anglickém jazyce.

Kódování

Všechny soubory v projektu by měly používat kódování UTF-8. Pokud nepracujete v prostředí, které používá kódování UTF-8, věnujte pozornost správnému nastavení editoru.

Pro Netbeans IDE kódování nastavte v menu ToolsOptions(Advanced options)EditingJava sourcesDefault encoding.

Nástroje

Na následujících řádcích se seznámíte s nástroji, které používáme při vývoji systému. Použití některých nástrojů není nutné, ale pokud se budete držet následujících doporučení, nebudete mít problémy s počátečním zprovozněním systému.

Subversion (SVN)

Subversion je nástroj pro správu verzí zdrojových kódů a pro týmový vývoj je naprosto nezbytný. Bez klienta SVN by nebylo možné stahování aktuálních zdrojových kódů systému a odesílání nových a upravených souborů se zdrojovými kódy do repository na vzdáleném serveru. Pokud jste ještě nikdy nepracovali se systémem pro správu verzí, přečtěte si úvodní kapitoly z knihy o Subversion.

Maven

Maven je nástroj pro správu softwarových projektů v jazyce Java (obdoba nástroje make nebo Ant). S jeho pomocí lze automatizovaně provádět různé úkony, jako například kompilace projektu, generování dokumentace, provádění a záznam výsledků testů, na základě informací o projektu soustředěných v tzv. objektovém modelu projektu (POM).

Maven je nástroj velice mocný, ale nemusíte se obávat jeho složitosti. Projekt XIQE má již připravenou konfiguraci a pro běžnou práci vystačíte se znalostí malého počtu příkazů. Při práci s pluginem ve vývojovém prostředí Netbeans rozdíl téměr nepoznáte (více informací o pluginu najdete na následujících řádcích).

Při vývoji XIQE používáme verzi 1.0.2. V budoucnu se počítá s přechodem na aktuální verzi 2.0, jakmile bude dostupný plugin pro vývojové prostředí Netbeans (viz XIQE/Project management).

Instalace

Pokud pracujete na fakultních strojích, je zprovoznění Mavenu otázkou jednoho příkazu:

 module add maven-1.0.2

Pro instalaci na vlastní počítač si stáhněte balíček adresy http://maven.apache.org/maven-1.x/start/download.html. Pro systém Windows je k dispozici spustitelný instalátor.

Pro instalaci v systému Linux postupujte následovně:

  1. Stažený balíček rozbalte do zvoleného adresáře (v tomto případě /opt/maven-1.0.2).
  2. Ve startovacím skriptu (například .bash_profile) nastavte proměnnou MAVEN_HOME s cestou do adresáře s instalací Mavenu:
 MAVEN_HOME=/opt/maven-1.0.2
 export MAVEN_HOME
  1. Ve startovacím skriptu přidejte adresář MAVEN_HOME/bin do proměnné PATH:
 PATH=$PATH:$MAVEN_HOME/bin
 export PATH

Základní instalace je hotova, v obou případech si můžete funkčnost instalace ověřit v konzoli příkazem

 maven --version

Pokud je vše vpořádku, měli byste obdržet podobnou odezvu:

  __  __
 |  \/  |__ _Apache__ ___
 | |\/| / _` \ V / -_) ' \  ~ intelligent projects ~
 |_|  |_\__,_|\_/\___|_||_|  v. 1.0.2


Práce v offline režimu

Netbeans

Developer Collaboration

Developer Collaboration plugin pro Netbeans IDE je dobrý nástroj pro komunikaci členů týmu. Účastníci chatu mohou mezi sebou sdílet zdrojové soubory, což je užitečné při řešení problémů.

Návod na instalaci pluginu najdete na adrese http://www.netbeans.org/kb/articles/quickstart-collaboration.html.

Pro obecnou diskusi o XIQE je založena místnost xiqe.

Mevenide Plugin

Mevenide je plugin pro práci s Mavenem dostupný ve verzích pro nejrozšířenější vývojová prostředí. Zde je popsána instalace pluginu pro vývojové prostředí Netbeans. Modul je podporován jak ve verzi Netbeans 4.x tak ve verzi 5.0 Beta.

Nejjednodušší možností je instalace prostřednictvím modulu autoupdate. Pro unixové systémy je dobré se před vlastní instalací přesvědčit, že můžete zapisovat do adresáře s instalací Netbeans. Pokud není povolen zápis, stačí dočasně povolit zápis do adresáře příkazem chmod o+w -R /opt/netbeans. Cestu do adresáře upravte podle vlastní instalace.

  1. Na adrese http://mevenide.codehaus.org/download/mevenide-netbeans-autoupdate-1.0.nbm si stáhněte modul autoupdate.
  2. V prostřední Netbeans v menu Tools zvolte možnost Update Center.
  3. V okně průvodce zvolte možnost Install Manually Downloaded Modules (.nbm Files) a stiskněte tlačítko Next.
  4. V dalším okně tlačítem add přidejte stažený soubor mevenide-netbeans-autoupdate.nbm a stiskněte tlačítko Next.
  5. V následujícím okně by se měla v pravém poli formuláře objevit položka Mevenide AutoUpdate Server. Stiskněte tlačítko Next.
  6. Po potvrzení licence se objeví další okno s dostupnými moduly k instalaci. Stiskněte tlačítko Finish.

Nyní máte nainstalovaný modul autoupdate a můžeme se pustit do vlastní instalace pluginu.

  1. V prostřední Netbeans v menu Tools zvolte možnost Update Center.
  2. V okně průvodce zaškrtněte novou položku Mevenide Update Center a stiskněte tlačítko Next.
  3. V následujícím okně vyberte všechny dostupné moduly pro instalaci. Ve verzi Netbeans 5.0 Beta nejde nainstalovat modul Mevenide XML Grammar, ale plugin bude funkční i bez něj.
  4. Po stažení všech modulů v dalším okně zaškrtněte políčka Include a Global u všech položek. Globální instalace je nutná, v opačném případě plugin nebude fungovat.
  5. Stiskněte tlačítko Finish a za malý moment by měla být instalace hotova.

První checkout z repository

Prvním krokem je stažení souborů projektu XIQE z repository. V adresáři, kam chcete soubory uložit, spusťte příkaz

 svn checkout https://www.bilysklep.cz/repos/xml/trunk/xiqe

Pro klienta ve Windows zvolte z nabídky operaci checkout a zadejte adresu repository uvedenou výše.

Soubory projektu naleznete po dokončení operace v nově vytvořeném adresáři xiqe, dále jej budeme nazývat jako kořenový adresář projektu. Podívejme se blíže na adresářovou strukturu projektu:

 xiqe 
   |--core 
   :    |--...
   :    |--project.xml    
   |--exex 
   :    |--...
   :    |--project.xml
   |--experiments 
   :    |--...
   :    |--project.xml
   |--maven-exex-plugin
   :    |--...
   :    |--project.xml
   |--storage
   :    |--...
   :    |--project.xml    
   |--doc
   |--LICENSE.txt
   |--project.properties
   |--project.xml

Důležitým souborem pro Maven je soubor project.xml, názývá se deskriptor projektu (project descriptor). V tomto souboru je uložen objektový model projektu. Z důvodu rychlosti práce se je systém XIQE fyzicky rozdělen do pěti podprojektů:

  • core
  • exex
  • experiments
  • maven-exex-plugin
  • storage

Každý podprojekt má svůj vlastní project descriptor, který dědí informace z rodičovského project descriptoru v kořenovém adresáři projektu. Při spouštění příkazů si Maven bere informace ze souboru project.xml v aktuálním adresáři, proto je dobré se vždy ujistit, že jste v adresáři podprojektu, se kterým zrovna chcete pracovat.

Adresářová struktura projektů následuje konvence pro správu projektů v Mavenu.

Pro začátek si zkusíme zkompilovat všechny podprojekty. Jednotlivé podprojekty jsou navzájem závislé a proto je nutné před prací s konkrétním podprojektem zkompilovat všechny ostatní projekty:

  1. v konzoli jako aktuální adresář zvolte kořenový adresář projektu
  2. spusťte příkaz
 maven multiproject:install

Tento příkaz zkompiluje všechny podprojekty a ve formě knihovny *.jar je zkopíruje do lokálního repository knihoven systému Maven (viz. Maven).

Tuto činnost byste měli provést vždy, když se změní zdrojový kód projektů, na kterých nepracujete. Před opakovanou kompilací můžete všechny projekty vyčistit příkazem

 maven multiproject:clean

Kompletní sadu příkazů pro práci s více projekty najednou si můžete zobrazit příkazem

 maven -P multiproject

Typický cyklus vývoje

Provádíme změny

Po prvním checkoutu je zdrojový kód aktuální. Pokud se však po delší době vracíte k rozdělané práci, je nanejvýš pravděpodobné, že mezitím někdo uložil své změny do repository. Abyste se vyhnuli problémům s konflikty, měli byste si před začátkem práce projekt sesynchronizovat s repository příkazem

 svn update

v kořenovém adresáři projektu.

Pro jistotu ještě projekt znovu zkompilujte (v kořenovém adresáři projektu):

 maven multiproject:clean multiproject:install

Pokud vše proběhlo v pořádku, můžete se pustit do práce.

Uložení hotové práce do repository

Před commitem změn do repository si zkontrolujte, zda váš zdrojový kód splňuje následující požadavky:

  1. Všechny nově vytvořené soubory, které chcete uložit do repository, jsou označené pro přidání (svn add).
  2. Ani po synchronizaci příkazem svn update se v projektu nevyskytují žádné konflikty. Může se stát, že někdo jiný provedl změny v souborech, se kterými jste pracovali. Pokud se nějaký konflikt vyskytne, vyřešte jej před commitem do repository.
  3. Celý projekt jde zkompilovat a všechny testy fungují. Nejsnáze ověříte příkazem v kořenovém adresáři projektu
 maven multiproject:clean multiproject:goal -Dgoal=test

Obecně platí, že do repository byste neměli ukládat rozdělanou práci, ale pouze ucelené změny. Kód, který je v repository by měl jít vždy zkompilovat a měl by být funkční. Usnadníte tak práci ostatním členům týmu. Snažte se také dodržovat stanovené konvence.