Pojmenování a verzování modulů a jejich .zip souborů

Moduly pro web KIV mají čísla verzí ve formátu M.m.p.e kde první dvě pozice (Major a Minor) určují verzi funkčnosti (dle dohody vývojářů, prj managera, a pokud možno dle souladu s cílovou verzí v milníku ve Flyspray), třetí pozice (Patch) indikuje opravy chyb bez přidání fčnosti, a čtvrtá pozice (Export) je ponechána k nastavování OpenCms při exportu modulu.

• před exportem modulu pro uložení jeho buildu vývojář v OpenCms nastaví v datech modulu (Administration > Module management > Edit module) verzi na M.m.p.0 tj. nastaví major a minor dle dohody a číslo exportu na nula, a do Description napíše aktuální datum a čas vydání
• výsledný .zip uložený v Subversion bude mít tedy název cz.zcu.kiv.modul_M.m.p.X.zip a po importu do OpenCms bude mít verzi M.m.p.X kde "X" je nezajímavé číslo vzniklé při exportu (nejčastěji z lokálního OpenCms) vývojářem.

Aktuální práce jsou identifikovány ohvězdičkovanými verzemi, tj. např. "Due in version = *Common 2.0" .

2. Úložiště v Subversion

Konfigurace OpenCms je v top-level adresáři opencms-libs spolu s potřebnými .jar soubory knihoven. TODO: Nekde by mela v top-level strukture modulu byt sdilena konfigurace pro pripojeni do db.

• pod pages/ rovnou JSPčka (ne tedy např. pages/osoby/neco.jsp) pro modul Osoby

• v Subversion musí být uložen každý "zbuildovaný" .zip modulu -- repository je referenční místo, odkud se moduly berou pro instalaci na ostrý web;
• každá verze modulu, která je určena pro nasazení (byť i jen v testovacím režimu např. na beta.kiv) musí mít tag v Subversion a tento tag v sobě musí obsahovat příslušné číslo verze modulu -- např. /temata/tags/temata_1.2.0/;
• .zip soubor modulu pro uložení v Subversion vzniká pouze a jedině exportem otestovaného a fungujícího modulu z (lokálního) OpenCms, nikoli ručním "zazipováním" nebo třeba ant scriptem (a je základní slušností ho před commitem zkusit naimportovat do čistého OpenCms, aby vývojář věděl, že mu to funguje).

Pojmenování a verzování modulů a jejich .zip souborů:

Moduly pro web KIV mají čísla verzí ve formátu M.m.p.e kde první dvě pozice (Major a Minor) určují verzi funkčnosti (dle dohody vývojářů, prj managera, a pokud možno dle souladu s cílovou verzí v milníku ve Flyspray), třetí pozice (Patch) indikuje opravy chyb bez přidání fčnosti, a čtvrtá pozice (Export) je ponechána k nastavování OpenCms při exportu modulu.

• před exportem modulu pro uložení jeho buildu vývojář v OpenCms nastaví v datech modulu (Administration > Module management > Edit module) verzi na M.m.p.0 tj. nastaví major a minor dle dohody a číslo exportu na nula, a do Description napíše aktuální datum a čas vydání
• výsledný .zip uložený v Subversion bude mít tedy název cz.zcu.kiv.modul_M.m.p.X.zip a po importu do OpenCms bude mít verzi M.m.p.X kde "X" je nezajímavé číslo vzniklé při exportu (nejčastěji z lokálního OpenCms) vývojářem.

Pro moduly: Milník se statusem "In development" je aktuálně ve vývoji, status "Assigned" je možné použít jako "jo tohle budeme chtít a plánujeme to jako další verzi"; status "New" je potenciální budoucí milník.

• výsledný .zip uložený v Subversion bude mít tedy název cz.zcu.kiv.modul_beta_M.m.0.zip (pro akceptaci tj. testování na beta.kiv) resp. cz.zcu.kiv.modul_M.m.0.zip (po akceptaci) a po importu do OpenCms bude mít verzi beta_M.m.0 resp. M.m.0.

• výsledný .zip uložený v Subversion bude mít tedy název cz.zcu.kiv.modul_beta_M.m.0.zip (pro akceptaci tj. testování na beta.kiv) resp. cz.zcu.kiv.modul_M.m.0.zip (po akceptaci) a po importu do OpenCms bude mít verzi M.m.0.

Pojmenování a verzování modulů a jejich .zip souborů:

Moduly pro web KIV mají čísla verzí ve formátu M.m.e kde první dvě pozice (Major a Minor) určují verzi funkčnosti (dle dohody vývojářů, prj managera, a pokud možno dle souladu s cílovou verzí v milníku ve Flyspray) a třetí pozice (Export) je ponechána k nastavování OpenCms při exportu modulu.

• každá verze modulu, která je určena pro nasazení (byť i jen v testovacím režimu např. na beta.kiv) musí mít tag v Subversion a tento tag v sobě musí obsahovat příslušné číslo verze modulu

Základní pravidla:

• v Subversion musí být uložen každý "zbuildovaný" .zip modulu -- repository je referenční místo, odkud se moduly berou pro instalaci na ostrý web
• každá verze modulu, která je určena pro nasazení (byť i jen v testovacím režimu např. na beta.kiv) musí mít tag v Subversion
• .zip soubor modulu pro uložení v Subversion vzniká pouze a jedině exportem otestovaného a fungujícího modulu z (lokálního) OpenCms, nikoli ručním "zazipováním" nebo třeba ant scriptem

Pojmenování a verzování

Protože každý export z OpenCms inkrementuje poslední číslo identifikátoru verze, platí:

• moduly v Subversion mají čísla ve formátu M.m.e kde první dvě pozice (Major a Minor) určují verzi funkčnosti (dle dohody vývojářů, prj managera, a pokud možno dle souladu s cílovou verzí v milníku ve Flyspray)
• před exportem modulu pro uložení jeho buildu vývojář v OpenCms nastaví v datech modulu (Administration > Module management > Edit module) verzi na M.m.0 tj. nastaví major a minor dle dohody a číslo exportu na nula, a do Description napíše aktuální datum a čas vydání
• výsledný .zip uložený v Subversion bude mít tedy název cz.zcu.kiv.modul_M.m.0.zip a po importu do OpenCms bude mít verzi M.m.0.

• v datech modulu (Administration > Module management > Edit module) se modulu do Description napíše datum a čas vydání

Ten datum a čas vydání v Description je nakonec jediný "trvalý" údaj, který přežije všechnu manipulaci s modulem v OpenCms (exporty, importy, modifikace). Je proto důležitý při hlášení chyb apod.

• po úpravách ověří, zda něco jinde nerozbili, projitím testovacích scénářů (viz Flyspray typ tasku "Test")

3. Struktura a build modulu

Struktura modulu

Struktura KIV modulů je založena na std OpenCms struktuře a z pohledu Subversion struktury vymyšlena taková, aby na ní šel dělat vývoj (viz také OpenCMS.VyvojModuluPodEclipse) a zároveň v ní byly dostupné hotové buildy nasazených modulů.

• Attach:struktura-modulu-pro-vyvoj--2009.png -- používaná struktura
• Attach:struktura-modulu-pro-vyvoj--2010-navrh.png -- návrh nové struktury pro snazší práci při vývoji

Pár pravidel:

• nevytvářet zbytečné adresáře -- např. templates/ pokud modul neobsahuje šablonové JSP
• pod pages/ rovnou JSPčka (ne tedy např. pages/osoby/neco.jsp)

Build a release

• Zapsat se do vývojářského mailing listu

• Zapsat se do http://groups.google.cz/group/kiv-web-dev?

• Používat postupy pro bugtracker, verzování, build

Build modulu

Verzují se, resp. v Subversion repo mají separátní top-level adresáře (v nich pak je std subversion struktura)

Struktura modulu

Je založena na OpenCms struktuře a z pohledu Subversion struktury vymyšlena taková, aby na ní šel dělat vývoj (viz také OpenCMS.VyvojModuluPodEclipse) a zároveň v ní byly dostupné hotové buildy nasazených modulů.

• Attach:struktura-modulu-pro-vyvoj--2009.png -- používaná struktura
• Attach:struktura-modulu-pro-vyvoj--2010-navrh.png -- návrh nové struktury pro snazší práci při vývoji

Pár pravidel:

• nevytvářet zbytečné adresáře -- např. templates/ pokud modul neobsahuje šablonové JSP
• pod pages/ rovnou JSPčka (ne tedy např. pages/osoby/neco.jsp

• Attach:struktura-modulu-pro-vyvoj--2009.png -- používaná struktura
• Attach:struktura-modulu-pro-vyvoj--2010-navrh.png -- návrh nové struktury pro snazší práci při vývoji

1. Bug tracker = Flyspray na forge.kiv

2. Verzování v Subversion

Úložiště přístupné pres Orion login+heslo na URL https://forge.kiv.zcu.cz/svn-www-kiv/.

Struktura modulu v úložišti

Verzují se, resp. v Subversion repo mají separátní top-level adresáře

V techto adr je std subversion struktura, v ní pak pro moduly struktura taková, aby na ní šel dělat vývoj (viz také OpenCMS.VyvojModuluPodEclipse) a zároveň v ní byly dostupné hotové buildy nasazených modulů.

• ?
• ? pro snazší práci při vývoji

Práce s úložištěm při vývoji

• Důvod: případné "uživatelské" jméno s diakritikou boří některé Subversion klienty, zejména cmdline a Tortoise, ve kterých pak nejde udělat checkout/update.

• Při commitu povinně psát komentáře !!! (pokud možno s referencí na Flyspray task ve formátu FS#123)

• POZN: možná opustíme, viz návrh nové struktury

Build modulu

Postup při release modulu a soulad vývoje, tagování a názvu modulu je:

Postup při release modulu

1. modul se dokončí (dle cíle iterace) na lokálním stroji ->
   • "BETA" tag v Subversion
   • cz.zcu.kiv.MODULENAME-M.m-BETA.zip balík modulu (ve jméně se inkrementuje M nebo m číslo verze dle cíle iterace -- např. cz.zcu.kiv.produkty-1.2-RC.zip z původního 1.1.zip)
2. beta se ověří a opraví na beta.kiv.zcu.cz, vzniká release kandidát ->
   • "RC" tag
   • cz.zcu.kiv.MODULENAME-M.m-RC.zip balík modulu
3. nasadí na www.kiv.zcu.cz a doladí se případné problémy, vzniká release ->
   • "RELEASE" tag
   • cz.zcu.kiv.MODULENAME-M.m.zip balík (bez "RELEASE", např. cz.zcu.kiv.produkty-1.2.zip).

1. ověří a opraví na beta.kiv.zcu.cz, vzniká release kandidát -> "RC" tag, cz.zcu.kiv.MODULENAME-M.m-RC.zip balík modulu (ve jméně se inkrementuje M nebo m číslo verze dle cíle iterace -- např. cz.zcu.kiv.produkty-1.2-RC.zip z původního 1.1.zip)
2. nasadí na www.kiv.zcu.cz@ a doladí se případné problémy, vzniká release -> "RELEASE" tag, cz.zcu.kiv.MODULENAME-M.m.zip balík (např. cz.zcu.kiv.produkty-1.2.zip@@).

• když začnou na nějakém dělat, změní stav na "In development" a případně upraví hodnotu odhadu pracnosti,

Postup při relese modulu

Soulad vývoje, tagování a názvu modulu je:

1. modul se dokončí (dle cíle iterace) na lokálním stroji -> "BETA" tag v Subversion
2. ověří a opraví na beta.kiv.zcu.cz, vzniká release kandidát -> "RC" tag, cz.zcu.kiv.MODULENAME-M.m-RC.zip balík modulu (ve jméně se inkrementuje M nebo m číslo verze dle cíle iterace)
3. nasadí na www.kiv.zcu.cz@ a doladí se případné problémy, vzniká release -> "RELEASE" tag, cz.zcu.kiv.MODULENAME-M.m.zip@@ balík.

• Při prvním přístupu do svn přes Eclipse a plugin SVNKit? budete dotázáni na zadání jména autora. Povinně zadejte svůj orion login, nesmí se zde zadat jméno(login) s diakritikou. Pokud jste náhodou již toto provedli, smažte v adresáři "Eclipse Home"/configuration/org.eclipse.core.runtime soubor .keyring a znovu spusťte Eclipse. Při přístupu do SVN budete opět dotázáni na jméno autora.

• Při commitu povinně psát komentáře !!!
• Před commitem změn src/.java modulu: zbuildovat .jar tříd pro modul, uložit ho do lib/ adresáře -- pak teprve commit

Před commitem změn src/.java modulu: zbuildovat .jar tříd pro modul, uložit ho do lib/ adresáře -- pak teprve commit

• výsledek: v svn jsou vždy v souladu zdrojáky a přeložené třídy k nasazení do OpenCms

• a pokud možno také používat OpenCmsBestPractices a OpenCmsTestovaniModulu

• Při psaní kódu modulů dodržovat ImplementacniKonvence a ArchitekturaModulu

• datový model a SQL DDL skripty

Co se neverzuje:

• projektové apod soubory pro IDE (např .project pro Eclipse), které má každý vývojář jiné

TODO: Nekde by mela v top-level strukture modulu byt sdilena konfigurace pro pripojeni do db.

• když začnou na nějakém dělat, změní stav na "In development" a případně upraví hodnotu odhadu pracnosti (skrytá pod Operating system),

• když mají hotovo, změní stav na "Requires testing", nastaví odhad pracnosti na skutečně strávený čas a teploměr na 90%, a dají "Request closure"

Základní pravidla a best practices pro práci s Flyspray-em. Vždy platí priority tasků dle RFC 2119 takto:

Detaily viz IteracniPlanovaniVeFlysprayi.

1. vytvořit verzi odpovídající cíli iterace (název dle cíle, ne dle toho kdo bude dělat - tj. např. "Produkty upgr" nikoli "PIA LS 2008-2009")

Iteration planning s Flysprayem:

• využít co nejvíc default fčnost - řazení tasků je default sestupně dle severity, stránka Roadmap ukazuje cosi jako burndown pro verze

1. vytvořit verzi odpovídající cíli iterace
2. vytvořit milník, přiřadit mu tuto verzi a due date
3. taskům nastavit priority vzhledem k iteraci dle tabulky výše
4. assign - napřed genericky "ASWI, PRJ" apod + po vyřešení personálního obsazení týmu přidat konkrétní lidi

Bug tracker Flyspray na forge.kiv

Základní pravidla a best practices pro práci s Flyspray-em.

Vývojáři

Leader

• dělají jen tasky, které mají přiřazené,
• když začnou na nějakém dělat, změní stav na "In development",
• si budou aktualizovat "teploměr" u svých tasků,
• když mají hotovo, změní stav na "Requires testing" a dají "Request closure"

Vývojářské typy tasků:

• Ke každému milníku je definována future Version v Project management
• Všechny tasky, které jsou naplánovány do iterace, mají dle předchozích dvou bodů nastaveno Due in version. (Optimálně by milník měl mít nastavenu dependency na podřízené tasky, ale to je hodně práce.)
• Stav milníku je pak možno sledovat na Roadmap stránce.

• Milník má nastaven max Severity a Priority (aby byl vždy nahoře ;-). V názvu milníku nechť je stručně uveden cíl a rámcový datum dosažení, viz Plan.

Stručně

• Používat bugtracker a verzování

Bug tracker

• Milník má nastaven max Severity a Priority (aby byl vždy nahoře ;-). V názvu milníku nechť je stručně uveden cíl a rámcový datum dosažení, viz Plan.
• Všechny tasky, které jsou naplánovány do iterace, mají dle toho nastaveno Due in version. Optimálně by milník měl mít nastavenu dependency na podřízené tasky.
• Priority tasků dle RFC 2119 takto:

• Dodržovat PouzivaneTechnologie

Vývojáři:

• si budou aktualizovat "teploměr" u svých tasků, které jsou:

Leader:

• používá plánovací tasky takto:

Priority záznamů dle RFC 2119

Plánovací tasky:

Pracovní tasky:

Platí, že Priority:High = MUST, Priority:Normal = SHOULD, Priority:Low = MAY (zejména vzhledem k iteraci definované Due in version a odpovídajícím milníkem).

• Při psaní front-endu aplikací používat VzhledoveKonvence

• Při psaní kódu modulů dodržovat ImplementacniKonvence

Priority záznamů dle RFC 2119

Leader:

Priority záznamů dle

• Milník má nastaven max Severity a Priority (aby byl vždy nahoře ;-). V názvu milníku nechť je stručně uveden cíl a rámcový datum dosažení, viz Plan.
• Všechny tasky, které jsou naplánovány do iterace, mají dle toho nastaveno Due in version. Optimálně by milník měl mít nastavenu dependency na podřízené tasky.

Typy záznamů v bugtrackeru:

• V názvu milníku nechť je stručně uveden cíl a rámcový datum dosažení, viz Plan.

• Při psaní kódu modulů dodržovat ImplementacniKonvence a instrukce zde

Stručně

• Používat PouzivaneTechnologie
• Používat bugtracker a verzování
• Moduly psát podle instrukcí zde
• Když nevím, hledat v manuálech

Lokalizace (L10N?)

Subversion přístupné pres Orion login+heslo na URL https://forge.kiv.zcu.cz/svn-www-kiv/.

• globální dokumentace
• grafické návrhy a šablony

Vývoj je přírůstkový a cca iterativní - co přírůstek to iterace (zatím). Každý přírůstek má well defined cíl a datum dokončení, viz Plan?.

Obsah stránky:

• Moduly v OpenCms
• Bugtracker
• Verzování

Moduly v OpenCms

Struktura

Držet se OpenCms konvencí

Podadresáře resources, pages, lib, classes atd. (viz třeba org.opencms.frontend.photoalbum nebo org.opencms.frontend.layoutpage).

Výkonný kód

Zabezpečení, autentikace a autorizace

Bug tracker

Verzování

Zpět na RedSys

Struktura

držet se OpenCms konvencí - podadresáře resources, pages, lib, classes atd. (viz třeba org.opencms.frontend.photoalbum nebo org.opencms.frontend.layoutpage).

Název

Musí mít ve VFS předponu cz.zcu.kiv následovanou inteligentním jménem modulu.

Výkonný kód

V JSP stránkách

Snažit se využít POJO a JSTL pro JSP stránky. Vlastní značky (taglib) vytvářet jen v odůvodněných případech a po schválení vedením projektu.

Zdrojové Java třídy

Musí být dobře pojmenovaném v balíku (dle názvu modulu do kterého patří) umístěném pod cz.zcu.kiv.opencms.

Přístup do DB

Používat Spring JDBC, třídy v balíku pod cz.zcu.kiv.db, podle ArchitekturaDaoVrstvy.

Lokalizace (L10N?)

Kam L10N? řetězce

Využívat možností OpenCms (properties VFS objektu, jazykové mutace XML strukturovaných dat). Pro JSP použít <c:if> nebo <c:switch> -- předpoklad je že v JSP bude málo textů závislých na jazyce, proto nebudou používány .properties lokalizační bundly.

Editační JSP stránky

Pro vlastní KIV aplikace budou vždy pouze v CZ (prezentační stránky jsou česky a/nebo anglicky).

Jak se zjistí aktuální locale

TBD

Zabezpečení, autentikace a autorizace

Autentikace

(ověření jména/hesla) Zatím (3/2008) přes OpenCms, v budoucnu přes Kerberos (viz ZabezpecenePrihlaseni).

Autorizace

(kdo kam může) Řešit prostředky OpenCms (Permissions na VFS objektu) nikoli v aplikační logice.

Zjištění aktuálně přihlášeného uživatele

Pro potřeby JSP aplikačních stránek - TBD.

Pro přístup do DB používat Spring JDBC, třídy v balíku pod cz.zcu.kiv.db -- viz ArchitekturaDaoVrstvy.

Pro přístup do DB používat Spring JDBC, třídy v balíku pod cz.zcu.kiv.redsys -- viz ArchitekturaDaoVrstvy.

Moduly v OpenCms

Struktura: držet se OpenCms konvencí - podadresáře resources, pages, lib, classes atd. (viz třeba org.opencms.frontend.photoalbum nebo org.opencms.frontend.layoutpage).

Název: Musí mít ve VFS předponu cz.zcu.kiv následovanou inteligentním jménem modulu.

Zdrojové Java třídy: Musí být dobře pojmenovaném v balíku (dle názvu modulu do kterého patří) umístěném pod cz.zcu.kiv.opencms.

Pro přístup do DB používat Spring JDBC.

Snažit se využít POJO a JSTL pro JSP stránky. Vlastní značky (taglib) vytvářet jen v odůvodněných případech a po schválení vedením projektu.

Nekde by mela v top-level strukture modulu byt sdilena konfigurace pro pripojeni do db.

Vývoj je přírůstkový a cca iterativní - co přírůstek to iterace (zatím). Každý přírůstek má well defined cíl a datum dokončení, viz Plan.

Bug tracker

Určuje náš život - co do kdy je třeba udělat.

Leader:

• Ke každému iteračnímu cíli je definován task s type=Milník a maximálními hodnotami Severity a Priority (aby byl vždycky nahoře :-) . V názvu milníku nechť je stručně uveden cíl a rámcový datum dosažení, viz Plan.
• Všechny tasky, které jsou naplánovány do iterace, mají dle toho nastaveno Due in version. Optimálně by milník měl mít nastavenu dependency na podřízené tasky.

Vývojáři:

• si budou aktualizovat "teploměr" u svých tasků.

Verzování

Subversion přístupné pres Orion login+heslo na URL -- TBD .

Verzovat se budou, resp. v Subversion repo budou mit separatni top-level adresare

• jednotlivé moduly

V techto adr uz std subversion struktura.

Nekde by mela v top-level strukture fav modulu maji byt sdilena konfigurace pro pripojeni do db.

Vývojáři:

• Při commitu povinně psát komentáře !!!
• Po dokončení iterace/přírůstku otagovat příslušné moduly atd.

Moduly v OpenCms

Musí mít ve VFS předponu cz.zcu.kiv následovanou inteligentním jménem modulu.