DOKUMENTTIENHALLINTASUUNNITELMA Versio 1.1 Edited by Checked by Approved by Harri Kauhanen Antti Tuomaala
i Sisällysluettelo DOKUMENTIN VERSIOT 1 1. JOHDANTO 2 1.1. Dokumentin tarkoitus ja kattavuus 2 1.2. Viittaukset muihin dokumentteihin 2 1.3. Määritelmät, termit, lyhenteet ja merkintätavat 2 2. PROJEKTIN KOTISIVU 3 2.1. Yleistä 3 2.2. Palvelimet 3 2.3. Hakemistorakenne 3 2.4. Versionhallinta 3 2.5. Varmuuskopiointi 3 3. PROJEKTIDOKUMENTOINTI 4 3.1. Yleistä 4 3.2. Mallipohjat 4 3.3. Tiedostojen nimeänen 4 3.4. Asiakirjojen muotoilu 4 3.5. Versionumerostandardi 5 3.6. Dokumenttien jakaminen 6 3.7. Dokumenttien kommentointi 6 3.8. Dokumenttien julkaiseminen 7 4. TEKNINEN DOKUMENTOINTI 8 4.1. Yleistä 8 4.2. Tiedostojen sijainti ja nimeäminen 8 4.3. Tekninen suunnittelu ja mallinnus 8 4.4. Lähdekoodin dokumentointi 9
ii Sisällysluettelo 5. OHJELMOINTIKÄYTÄNNÖT 10 5.1. Käytetyt työkalut 10 5.2. Versionhallinta 10 5.2.1. Yleistä 10 5.2.2. Tiedostojen muokkaus 11 5.2.3. VYM ohjelmiston versionumerointi 11 5.2.4. Moduulien sisäinen versionumerointi 12 5.2.5. Testaus 13 5.3. Lähdekoodi 13 5.3.1. Yleistä 13 5.3.2. Käytetty kieli 13 5.3.3. Lähdekoodin käytännöt 13 5.3.4. API dokumentointi 13 5.4. Ohjelmien kääntäminen 14 5.4.1. Normaali kääntäminen 14 5.4.2. Levityspakettien teko 14
1(16) Dokumentin versiot Vers Muuttaja Pvm Muutos Tarkastanut Hyväksynyt 1.0 Harri Kauhanen 2.10.2000 Alkuperäinen versio Luonnos 1 1.0 Harri Kauhanen 7.10.2000 Tarkennettu luonnosversio Luonnos 2 1.0 Harri Kauhanen 11.10.2000 Pieniä korjauksia, joita todettiin dokumentin läpikäynnissä. Muutama kirjoitusvirhe ja täsmennys. Luonnos 3 1.1 Harri Kauhanen 17.11.2000 Lisätty kokonaan uusi luku 5 Ohjelmointikäytännöt. Kappaleessa käsitellään ohjelmoinnin työkaluja, versionhallintaa ja ohjelmointikäytäntöjä. 1.1 Harri Kauhanen 11.12.2000 Pieniä korjauksia ja täsmennyksiä poistettu XML kirjaston käyttö, koska toteutetaan oma parseri JavaDoc kommenttien oppaan linkki korjattu 1.2 Harri Kauhanen 23.4.2001 Yksinkertaistettu liian monimutkaista versionumerointia. Lisätty käännösohjeet Ant:n avulla. Luonnos 1 Luonnos 2 Antti Tuomaala
2(16) 1. Johdanto 1.1. Dokumentin tarkoitus ja kattavuus Tämän dokumentin tarkoitus on määritellä projektiryhmälle yhteneväiset tavat hoitaa projektiin liittyvä dokumentointi, ohjelmakoodi ja niiden versionhallinta. Omaan työskentelytyyliin, nimeämiskäytäntöön jne. tottuneelle ennalta määrättyjen linjojen noudattaminen voi tuntua hankalalta. Yhteiset työskentelytavat toivottavasti kuitenkin enemmän edesauttavat kuin haittaavat projektin menestyksekästä läpiviemistä. Joitakin etuja yhteisten työtapojen ja versionhallinnan määrittelemisestä: Dokumenttien yhtenäinen ulkoasu- ja rakenne helpottavat niiden lukemista ja ymmärtämistä. Dokumentit löytyvät aina yhdestä paikasta. Dokumenttien perään ei tarvitse kysellä tai kadonneita versioita etsiskellä. Yhteisten työkalujen käyttö mahdollistaa sen, että kuka tahansa voi muokata dokumentteja. Ohjelmakoodin läpikäynti on tarkastajalle helpompaa. Työskentelyssä voidaan palata vanhoihin versioihin. Esim. kokeilujen teko on helpompaa. Saman lähdekoodin käsittely ryhmän jäsenten välillä helpottuu. Varmuuskopiointi voidaan keskittää. 1.2. Viittaukset muihin dokumentteihin Nro Dokumentti Selitys ja talletuspaikka 1 Laatusuunnitelma Laatusuunnitelma kuvaa projektin läpiviemisen laadukkaasti ja esittelee mittareita toteutuneen laadun seurantaan. 2 Ohjelmointiympäristö VYM projektissa (muistio) Ohjelmien asennus ja joitakin tärkeimpiä käyttöohjeita. 1.3. Määritelmät, termit, lyhenteet ja merkintätavat Termi, käsite, merkintätapa Versionhallinta Selitys, määritelmä Dokumenttien ja lähdekoodin hallinta siten, että kustakin tiedostosta voi versionhallintajärjestelmässä olla useita versioita. Versionhallinta mm. mahdollistaa paluun vanhaan versioon ja sen, että useampi kuin yksi pystyy työskentelemään saman lähdekoodin parissa.
3(16) 2. Projektin kotisivu 2.1. Yleistä Projektin kotisivun on tarkoitus toimia tuotetun tiedon säilytyspaikkana. Projektin luonteesta johtuen ryhmän jäsenet saattavat työskennellä eri paikoissa, joten julkiset http- ja ftp palvelimet auttavat ryhmän työskentelyä. Dokumenttien lähdekoodi (Word tiedostot) pidetään salasanan takana, mutta kaikki palautettava materiaali julkaistaan.pdf muodossa. 2.2. Palvelimet Palvelin http://hazard.iki.fi/vym ftp://hazard.iki.fi/ Selitys Projektin kotisivu. Etusivulle ja palautuksiin kaikilla vapaa pääsy, mutta jotkin osat suojataan salasanalla. Käyttäjätunnus ja salasana toimitetaan jäsenille henkilökohtaisesti. Projektin ftp palvelin. Dokumenttien jakaminen ja mallipohjien hakeminen omalle koneelle. Käyttäjätunnus ja salasana samat kuin web palvelimella. 2.3. Hakemistorakenne Hakemisto /vym/ /vym/palautukset/ /vym/src/ /vym/src/doc /vym/src/doc/template /vym/src/old/ Selitys Projektin etusivu. Palautuksille perustetaan omat kansiot. Kansiosta löytyy vähintään index.php (palautuksen etusivu) xxx.pdf (dokumentit) /src/xxx.doc (Word ja muut dokumentit, salasanalla suojattu) Kaikki mahdollinen lähdekoodi. Myös dokumenttien.doc tiedostot ajatellaan olevan lähdekoodia. Salasana suojattu. Kaikkien projektidokumenttien lähdekoodi. Dokumenteissa käytetyt kuvat (kaaviot yms.) Jokaisella dokumentilla oma kansio. Mallipohjat dokumentteja varten. Kansio yksinkertaista versionhallintaa/varmuuskopiointia varten. 2.4. Versionhallinta Dokumenttien vanhojen versioiden säilytystä varten on olemassa old kansio. Ohjelmakoodille toteutetaan oikea versionhallinta, mutta muun dokumentoinnin köyhän miehen versionhallinta perustuu eri palautusvaiheissa tehtyihin tilannekopioihin (ks. luku 3.8) ja ryhmän jäsenten omiin versiotallennuksiin old kansioon. 2.5. Varmuuskopiointi Kaikki projektin kotisivun alla olevat tiedostot varmuuskopioidaan automaattisesti kerran vuorokaudessa.
4(16) 3. Projektidokumentointi 3.1. Yleistä Projektin varsinainen dokumentointi kirjoitetaan Microsoft Word 97/2000 ohjelmalla. Pohjana käytetään soveltaen Comptelin valmiita dokumenttipohjia. Yleisesti on parempi noudattaa kurssin kotisivuilta löytyvien dokumenttipohjien rakennetta, mutta soveltaen voi myös käyttää omien dokumenttipohjien tarjoamia vinkkejä otsikointiin ja sisällöksi. 3.2. Mallipohjat Mallipohjat löytyvät projektin kotisivujen alta ja projektin FTP palvelimen alta. Käyttäjätunnukset ja salasanat toimitetaan projektin jäsenille henkilökohtaisesti. 3.3. Tiedostojen nimeänen Tiedostojen nimeämiseksi on käytössä yksinkertainen käytäntö. Dokumentin tiedostonimeksi annetaan dokumentin nimi siten että käytetään vain pieniä eiskandinaavisia kirjaimia ja välilyönnit korvataan _ (alaviiva) merkillä. Dokumentin versionumeroa ei sisällytetä tiedostonimeen. Tiedostotunniste on luonnollisesta.doc. Esimerkki hyväksyttävästä nimestä: vaatimusmaarittely.doc Nimeämistä voi erityisesti perustella sillä, että dokumentteihin saatetaan tehdä viittauksia HTML tiedostoista. Tällöin em. muodossa olevat tiedostonimet toimivat paremmin. Kommentoidut dokumentit nimetään kuitenkin kommentin tekijän mukaan lisäämällä alkuun kommentoijan nimi tai nimikirjaimet. Esim. harri_kommentit_testaussuunitelma.doc Tämä johtuu käytännön syistä, jotta jokainen voisi antaa omat henkilökohtaiset kommenttinsa. Katso lisää kappaleista 3.6 ja 3.7. 3.4. Asiakirjojen muotoilu Asiakirjojen muotoilussa on syytä käyttää tekstinkäsittelyohjelman ominaisuuksia. Tässä dokumentissa ei kuitenkaan opasteta tekstinkäsittelyn ominaisuuksia. Muutamana vinkkinä kannattaa kuitenkin muistaa seuraavat kohdat: Käytä otsikkotyylejä. Nimeä kuvat ja taulukot käyttäen Wordin luettelo-ominaisuuksia.
5(16) Käytä ristiviittauksia (älä viittaa kappaleeseen 2.3 kirjoittamalla kaksi piste kolme, vaan valitse Lisää ristiviite ominaisuus). Koeta pärjätä kolmella otsikkotasolla. Neljä on ehdoton maksimi. 3.5. Versionumerostandardi Asiakirjan sisällä pidetään kirjaa tehdyistä muutoksista. Dokumentin alkupuolella on taulukko versiohistoriasta, jota tulee päivittää aina, kun on tehty riittäviä muutoksia ja aina ennen kuin dokumentti lähetetään projektin kotisivulle. Wordin sisäistä versionhallintaa tulee käyttää vähintään silloin, kun dokumentista julkaistaan uusi hyväksytty versio. Sisäinen versionhallinta otetaan käyttöön Wordissa valitsemalla valikoista Tiedosto / Versio Standardi Versio n.m (luonnos x) Versio n.m Selite Työn alla oleva x:s luonnos tulevasta versiosta n.m Hyväksytty versio. ylivoimaisesti yleisin muoto on n.0, eli m:n arvona on nolla, muut muodot ovat korjauksia versioihin n.0 Nimen osat n m x Selite Versionumero (major). Numerointi alkaa numerosta 1 ja jatkuu 2, 3, 4, Version tarkenne (minor). kun versionumeroa vaihdetaan, tarkenne m nollataan 0:ksi. numeroita 1, 2, 3 käytetään, kun hyväksyttyyn versioon tehdään pieniä muutoksia, esim. korjataan sanamuotoja tai kirjoitusvirheitä Luonnoksen tarkenne. Numerointi alkaa numerosta 1 ja jatkuu 2, 3, 4, Esimerkki Selite Versio 1.0 (luonnos 1) Alkuperäinen, työn alla oleva luonnos tulevasta versiosta 1.0 Versio 1.0 (luonnos 2) Seuraava muokattu, mutta vielä työn alla oleva luonnos versiosta 1.0 Versio 1.0 (luonnos 3) Luonnos 2:sta edelleen muokattu => luonnos 3 Versio 1.0 Versio 1.1 (luonnos 1) Versio 1.1 Versio 2.0 (luonnos 1) Versio 2.0 (luonnos 2) Versio 2.0 Versio 3.0 (luonnos 1) Dokumentin 1.0 hyväksytty ja julkaistu versio Versioon 1.0 tehdään pieni korjaava muutos. Dokumentti on 1. luonnos tulevasta versiosta 1.1. Dokumentin 1.1 hyväksytty versio Viimeisimmän version 1.1 sisältöön tehdään muutoksia. Dokumentti on 1. luonnos tulevasta versiosta 2.0 Edellisestä on muokattu ja se on valmis kommenteille vietäväksi => luonnos 2 Dokumentin 2.0 hyväksytty ja julkaistu versio Jne.
6(16) 3.6. Dokumenttien jakaminen Dokumentteja voi kukin muokata haluamassaan paikassa. Kun dokumentti halutaan muiden tarkasteltavaksi, hyvä käytäntö on siirtää ne ensin FTP ohjelmalla projektin kotisivujen /src/doc/ kansioon ja lähettää asianosaisille linkki ko. dokumenttiin. Dokumenttien lähettämistä suoraan sähköpostin liitteenä on syytä välttää. Syyt tähän ovat ilmeiset esim. sähköpostilaatikkojen koko aiheuttaa monelle meistä ongelmia. Omalla koneella muokkauksen alla oleva dokumentti on hyvä lähettää ftp:llä projektin kotisivulle aina kun muutoksia on tehty. Näin tiedostosta tehdään aina varmuuskopio. Samassa yhteydessä tulee päivittää dokumentin sisäinen versionumero. Vaikka kyseessä olisi vain pieni muutos, niin uusi luonnos numero on annettava ja kuvattava tehdyt muutokset (ks. luku 3.5). Samasta dokumentista ei koskaan saa olla kahta erilaista versiota samalla versionumerolla (luonnos tason numerointi mukaan luettuna). Kommentoidut dokumentit tallennetaan poikkeuksellisesti asiakirjakansion alakansioon kommentit. Esim. kansio voisi olla../src/doc/laatu/kommentit/ 3.7. Dokumenttien kommentointi Valmistauduttaessa läpikäynteihin, katselmointeihin tai pienempiinkin tilaisuuksiin tarvitaan usein kommentteja muilta dokumentteihin. Pienet kommentit voidaan toki esittää suullisesti tai sähköpostitse. Monesti on kuitenkin tarvetta laajempaan kommentointiin. Tällöin pyritään käyttämään hyväksi Wordin kommentointiominaisuuksia. Seikkaperäiset ohjeet kyseisen prosessin läpiviemiseen: Kirjoittaja kaivaa Wordin työkaluista työkalupaletin Tarkistaminen. Kirjoitetaan dokumentti. Merkitään erityistä huomiota vaativat kohdat Korostus työkalulla (tekstin tausta keltainen) ja lisätään Lisää kommentti työkalulla kommentteja. Jaetaan dokumentti kappaleen 3.6 mukaisesti. Kommentoija kaivaa Wordin työkaluista työkalupaletin Tarkistaminen. Valitaan Jäljitä muutokset työkalu, jolloin tehdyt muutokset näkyvät helposti. Tehdään muutokset. Erillistä korostusta ei tarvitse yleensä käyttää. Lisätään tarvittaessa kommentteja. Tallennetaan tiedosto ja laitetaan nimen alkuun oma nimi (ks. kappale 3.3).
7(16) Siirretään kommentoitu tiedosto projektin kotisivuille dokumentin omaan kansiossa olevaan kommentit kansion alle. Alkuperäinen muokkaaja tai muutoksen tekijä hakee alkuperäisen ja kommentoidut asiakirjat itselleen. Muokkaaja lataa alkuperäisen asiakirjan. Käytetään Wordin ominaisuutta Työkalut/Yhdistä asiakirjat jokaiselle kommentoidulle asiakirjalle. Muokataan asiakirja kuntoon, versioidaan, talletetaan uusi versio, siirretään ftp:llä palvelimelle ja kerrotaan muille homman olevan tehty. 3.8. Dokumenttien julkaiseminen Ennen katselmuksia ja palautuksia perustetaan projektin kotisivulle oma kansio palatusta varten. Palautuskansion alle luodaan src kansio, johon kaikki vaihepalautukseen liittyvä dokumentaatio kopioidaan. Tämän on tarkoitus toimia hyvin yksinkertaisena dokumenttien versionhallintana. Julkaistavat dokumentit muunnetaan Adobe Acrobat (.pdf) muotoon ja siirretään kunkin vaiheen omalle palautussivulle. Jokaista palautusta varten laaditaan kurssin etusivulta linkki palautussivulle (HTML). Kaikki palautukset ovat siis yleensä joko.pdf muodossa ja tarvittaessa voidaan käyttää myös HTML muotoa. Tätä prosessia ei tarkemmin määritellä, mutta julkaiseminen on pääasiassa laatuvastaavan ja projektipäällikön vastuulla.
8(16) 4. Tekninen dokumentointi 4.1. Yleistä Tässä osassa teknisellä dokumentoinnilla tarkoitetaan kaikkea muuta kuin tekstinkäsittelyohjelmalla tuotettua dokumentointia tai ohjelman lähdekoodia. Sen sijaan tässä osassa kuvattua teknistä dokumentointia voi käyttää normaalin dokumentoinnin apuna esimerkiksi kuvina tai varsinaisen dokumentin liitteenä. 4.2. Tiedostojen sijainti ja nimeäminen Syntyvien tiedostojen nimeämiselle ei ole muuta sääntöä, kuin että nimen on syytä olla riittävän kuvaava. Esimerkiksi jos dokumentti sisältää Profiili luokan luokkakaavion, niin nimestä olisi käytävä riittävän selvästi luokan nimi ja se, että kyseessä on luokkakaavio. Joissakin tapauksissa tiedostotunniste voi olla riittävä kuvaamaan dokumentin tyypin, mutta yleensä tarvitaan tarkennuksia sopivaa nimeä valittaessa. Nimen kirjoitusasun tulisi noudattaa kappaleessa 3.3 esitettyä tapaa eli käytetään vain pieniä kirjaimia ja välilyönnit korvataan alaviivalla. Tiedostojen sijainti on tapauskohtainen, eikä sille voi esittää yksiselitteisiä sääntöjä. Paras sääntö on se, että tiedostot tulee tallettaa mahdollisimman tarkoituksenmukaiseen paikkaan. Mitä tämä milloinkin tarkoittaa on tulkinnanvaraista, mutta joitakin suuntaviivoja voimme tässä yrittää esittää. Tyyppi Yksittäinen kuva/kaavio, joka liittyy ensisijaisesti varsinaiseen dokumenttiin. Laajempi tekninen kokonaisuus, jonka kuviin/kaavioihin viitataan useista dokumenteista. Mahdollinen talletuspaikka Talletetaan samaan kansioon varsinaisen dokumentin kanssa. Esim. projektisuunnitelmaan liittyvä organisaatiokaavio voisi olla esimerkki tällaisesta tapauksesta. Mikäli kuvia on paljon (>5) niin kuvia varten on syytä perustaa oma alikansio. Perustetaan /src/doc/ alle oma kansio, johon dokumentit talletetaan. Esimerkiksi koko projektin luokkakaavio on kokonaisuus, joka vaatinee oman kansion. Joskus kokonaisuus on ratkaisevan iso ja silloin voidaan kansio perustaa suoraan /src/ kansion alle. Esimerkiksi ohjelman lähdekoodi edustaa tällaista isoa kokonaisuutta. Oleellista on kuitenkin se, että muutkin kuin Word ohjelmalla tuotetut dokumentit on syytä tallettaa projektin hakemistojärjestelmään. Vaikka tehty kuva/kaavio näkyisikin Wordissa, voi sen päivittäminen tulla myöhemmin kysymykseen. Turhalta etsimisvaiheelta vältytään, kun kaikki tarvittavat tiedostot ovat saatavilla. 4.3. Tekninen suunnittelu ja mallinnus Projektin suunnittelun eri käytetään UML mallinnusta. Mallien tuottamisen apuna käytetään Rational Rose ohjelmistoa. Ohjelmistolla tuotettuja kuvia ja kaavioita käytetään yleensä varsinaisissa dokumenteissa kuvina tai liitteinä. Itsenäisesti ne toimivat toteutuksen apuna ja mahdollisuuksien mukaan voidaan käyttää myös
9(16) ohjelmiston tarjoamia työkaluja esimerkiksi automaattisen koodirungon tuottamiseen luokkakaaviosta. Myös muita työkaluja voidaan käyttää niiltä osin, kun Rosen ominaisuudet eivät riitä tai jos mallintaminen on ratkaisevasti helpompaa. 4.4. Lähdekoodin dokumentointi Lähdekoodin tekninen dokumentointi tehdään suoraan lähdekoodiin käyttäen JavaDoc merkintöjä. Näistä merkinnöistä tuotetaan myöhemmin automatisoituja työkaluja käyttäen HTML ja/tai Adobe Acrobat tyyppiset dokumentit. Suoraan lähdekoodiin sisällytettävät JavaDoc merkinnät esitetään luvussa 5.3.
10(16) 5. Ohjelmointikäytännöt 5.1. Käytetyt työkalut Oheiseen taulukkoon tarkennetaan projektisuunnitelmassa esitettyjä työkaluja. Kaikki ohjelmat löytyvät VYM palvelimelta osoitteesta http://hazard.iki.fi/vym/software sekä kaikille jaettavalta VYM-CD:ltä. Työkalu JDK 1.2.2 (tai JDK 1.3) CVS 1.10 Ant Oracle 8 ja PostreSQL (+ PSQL JDBC) Tomcat Selitys Java kehitysympäristö. Projektissa pyritään pärjäämään mahdollisimman pitkälle JDK:n omilla kirjastoilla. Hallintatyökalua kannattaa ajaa javan 1.3 versiolla, jossa on korjattu käyttöliittymäkomponenttien bugeja. Versionhallintaohjelmisto. Lähdekoodin jaettu säilytyspaikka on VYM palvelin, mutta CVS versionhallinnan avulla jokainen voi työskennellä haluamassaan paikassa ja mahdollisimman tuore koodi on kuitenkin kaikkien saatavilla. Make työkalu. Tietokanta, jota käytetään JDBC rajapinnan kautta kyselykielenä SQL. Alkuvaiheessa käytetään ilmaista PostreSQL kantaa ja myöhemmin otetaan käyttöön Oracle (Comptelin standardikanta). JSP palvelin, jonka avulla toteutetaan käyttäjän portaali. Ohjelmien asennusta ei käsitellä tässä dokumentissa. Sen sijaan on laadittu erillinen muistio, joka on nimeltään ohjelmointiymparisto.pdf. Myös ohjelmien tärkeimmät toiminnot on listattu samaisessa muistiossa. Dokumenttienhallintasuunnitelmassa viitataan suoraan ohjelmien toimintoihin, mutta ei enää esitetä, miten mikäkin toiminta tehdään. Viime kädessä jokainen on itse vastuussa siitä, että opiskelee ohjelmien käytön. Laatuvastaava toimii ohjelmistojen teknisenä tukena. 5.2. Versionhallinta 5.2.1. Yleistä Versionhallinnassa käytetään siis apuna CVS ohjelmistoa. On huomattava, että CVS:n sisäinen versiointi on eri asia kuin ohjelman tai moduulien versiot. Tässä dokumentissa ei siis kerrota versionhallinnan komentoja, vaan käytetään hyväksi em. muistiota, ohjelman omia ohjeita. Lisäksi laaditaan on-line lista tärkeimmistä komennoista. Seuraavissa kappaleissa esitettyjä versiointinumerointeja käytetään jatkossa hyväksi, kun tarvitaan viitata ohjelman versioihin. Esimerkiksi testiraporteissa mainitaan, mitä versioita koko ohjelmistosta tai tietyistä moduuleista on käytetty.
11(16) 5.2.2. Tiedostojen muokkaus Kun halutaan muokata lähdekoodia on tehtävä seuraavat toimenpiteet: tarkista onko muita muokkaajia Jos on, niin selvitä tilanne (pyydä muokkaajaa commitoimaan tiedosto). Kiiretapauksissa viestitä muille muokkaajille, että teet muutoksia. Kun koodia on muokattu, se pitää palauttaa versionhallintaan: tarkista onko koodi toimivaa muutosten jälkeen jos ei, niin älä laita järjestelmään jos olet siinä vaiheessa kehitystä, että koodi ei voikaan olla vielä toimivaa, niin tee viimeisestä toimivasta versiosta leimat kappaleen 5.2.4 mukaan ja kerro muille käyttäjille miten toimiva versio valitaan käyttöön jos olet tekemässä todella isoa muutosta, niin tee muutosta varten oma haara (branch) versionhallintaan ja anna sille kuvaava nimi muutokset pitää päivittää (commit) versionhallintaan aina kun muutos on tehty ja todettu toimivaksi. edut: kaikilla on käytössä tuoreet versiot ja varmuuskopiointi toimii luotettavammin 5.2.3. VYM ohjelmiston versionumerointi Kehitettävän VYM ohjelmiston versionumero on periaatteessa 1.0. Koska kehitysvaiheessa ohjelmisto kehittyy huomattavasti, tarvitaan käyttöön kehitysversion oma sisäinen versionumerointinsa. Versioinnin rakenne on esitetty oheisessa taulukossa. Ohjelmiston versionumero Kehitysversion numero 1.0.0 dev int. 1.3.0 Tekstissä versionumerointi voidaan kirjoittaa lyhyesti muodossa 1.3 tarkoittaen aina nimenomaan kehitysversion numerointia.
12(16) Ohjelmiston versionumero Kehitysversion numero Ohjelmiston versionumeron pysyy muuttumattomana koko projektin ajan versiona 1.0.0 dev. Periaatteessa numerointi noudattaa muotoa MajorVersion.MinorVersion.BugFix status, mutta tässä yhteydessä tähän numerointiin ei tämän enempää puututa. Kehitysversio numeroidaan kolmella numerolla. Periaatteessa numerointi menee niin, että ensimmäistä numeroa kasvatetaan suurissa muutoksissa eli kun esimerkiksi päätetään muuttaa arkkitehtuuria. Toista numeroa kasvatetaan kehittämisen iterointikierrosten mukaan. Käytännössä uusi versionumero otetaan käyttöön aina projektin uuden vaiheen alussa ja vaiheen lopussa lyödään leimat lähdekoodiin versionhallinnan avulla. Kolmatta numeroa voidaan käyttää esim. uusintatestejä järjestettäessä, kun virheitä on korjattu, mutta ohjelman toiminta ei kuitenkaan ole muuttunut. Kun ohjelmasta tehdään paketteja, niin pyritään numerointi pitämään lyhyenä. Esimerkiksi: vym_1.3.0.zip Versionhallinnan leimat annetaan suoraan kehitysversion mukaan: vym_1-3-0 Laatuvastaava vastaa koko ohjelmistoa koskevista versioleimoista. 5.2.4. Moduulien sisäinen versionumerointi Moduulien versiointi elää omaa elämäänsä verrattuna koko ohjelmiston versionumerointiin. Periaate on samantapainen eli versiointi noudattaa perinteistä kolmen tason numerointia oheisen taulukon mukaan. Taso Major Minor Bugfix Esimerkki 1. 2. 0 Numeroinnin nosto Selkeät arkkitehtuuriset tai toiminnalliset muutokset Pienet muutokset sisäisesti tai rajapinnoissa. Pieni sisäinen muutos, ei muutosta rajapinnoissa. Moduulien sisäinen numerointi on erityisen hyödyllistä silloin, kun käytetään toisten tekemiä moduuleita ja tiedetään, että uusin versio ei toimi oikein (esim. kehitys on toimimattomassa vaiheessa tai uusi versio tarvitsee yhteyden kantaan jota ei ole tms.) Versionhallinnan komennoilla voidaan aina valita tilanteeseen sopiva versio ja itse moduulin kehittäjä voi jatkaa kehittelyään muita häiritsemättä. Sisäisen versionumeroinnin käyttö on moduulin omistajasta kiinni, mutta vähintäänkin on tehtävä uudet versiot isoissa muutoksissa ja silloin, kun on tiedossa, että muutos voi aiheuttaa muille kehittäjille ongelmia. Versionhallinnan leimat annetaan muodossa:
13(16) <moduulin_nimi>_1-2-0 Kunkin moduulin omistaja vastaa leimojen antamisesta. 5.2.5. Testaus Aina kun suoritetaan ohjelmiston testausta, on koodi haettava leimojen mukaan. Leimaamatonta koodia ei saa testata. Testitilanteessa haetaan lähdekoodi kokonaan uudelleen (ei vanhan päälle) valittujen leimojen avulla (ei viimeisimmän version perusteella). Testausraporttiin kirjoitetaan selkeästi, mitä versiota on testattu ja mitä leimoja on käytetty. 5.3. Lähdekoodi 5.3.1. Yleistä Koska ohjelmointikieleksi on valittu Java, niin koodauskäytännöt ovat valmiiksi jo kohtalaisen selkeät. Projektissa pyritään pitäytymään yleisillä linjoilla ja tyydytään käyttämään SUN:n määrittelemiä tai muuten yleisesti hyväksyttyjä käytäntöjä. 5.3.2. Käytetty kieli VYM projektin dokumentointikieleksi on valittu suomi. Näin ollen kaikki ohjelman kommentointi ja API dokumentointi kirjoitetaan myös suomeksi. Sen sijaan kaikki muuttujat, tietorakenteet yms. kuvataan englanninkielisin termein. 5.3.3. Lähdekoodin käytännöt Lähdekoodin tyylioppaana käytetään SUN:n laatimaa Code Conventions for the Java TM Programming Language. Tämä opus löytyy osoitteesta: http://java.sun.com/docs/codeconv/html/codeconvtoc.doc.html Jokainen on osaltaan velvollinen tutustumaan oppaaseen ja noudattamaan siinä esiteltyjä käytäntöjä. 5.3.4. API dokumentointi Lähdekoodin sekaan upotetaan API dokumentaatio käyttäen SUN:n määrittelemiä JavaDoc merkintöjä. Teknisen dokumentaation kirjoittaminen helpottuu näin huomattavasti, kun osa dokumentoinnista saadaan suoraan lähdekoodista yhdellä komennolla. Merkintöjen käyttöä selvittävä opus löytyy osoitteesta: http://java.sun.com/j2se/javadoc/writingdoccomments/index.html Jokainen on osaltaan velvollinen tutustumaan oppaaseen ja noudattamaan siinä esiteltyjä käytäntöjä.
14(16) 5.4. Ohjelmien kääntäminen 5.4.1. Normaali kääntäminen Ohjelmien kääntämistä helpottamaan on kirjoitettu muutama Ant XML käännöskuvaus. Nämä on dokumentoitu suoraan XML tiedostoihin. Käännösvaihtoehdot saa tulostumaan seuraavalla komennolla (lähdekoodin juurihakemistosta) % ant ant [ all_clean vym_clean vym_compile vym_jar vym_dist admin_clean admin_compile admin_jar admin_dist portal_clean portal_compile portal_dist doc_clean doc_compile ] xxx_clean xxx_compile xxx_jar xxx_dist = Poistaa vanhan kaannoksen. = Kaantaa lahdekoodin builds/classes/ kansion alle Java-luokiksi. = Paketoi kaannetyt luokat JAR paketiksi builds/jars/ kansioon. = Kopioi JAR paketin, muut kirjastot, konffitiedostot ja kaynnistytskriptin kansioon builds/dist/ Esimerkiksi hallintatyökalu käännetään täydellisesti komennolla % ant admin_dist 5.4.2. Levityspakettien teko Levitettävien versioiden teko on hieman hankalampaa. Lisäksi käännösprosessi on melko buginen, joten näitä tehdessä on syytä olla huolellinen. Valmistelevat toimenpiteet: anna versionhallinnassa moduuleille (Java lähdekoodille) versio, esimerkkejä: vym_1-2-3 (joka koostuu esim. seuraavista moduuleista) vym_main_1-2-3 vym_db_1-1-0 amok_1-4-1 vym_admin_1-2-2 vym_portal_1-3-0 Määrittele portaalin tai hallintatyökalulle, mitä VYM versiota aiotaan käyttää eli muokkaa esim. tiedostoa (itsedokumentoiva tiedosto) {sorsat}/etc/admin/admin.properties
15(16) Päivitä versiohistoria, esim. {sorsat}/etc/admin/doc/admin.history Tarkista, että muut paketin mukaan tulevat tiedostot ovat kunnossa (kaikki etc kansion alapuolella olevat tiedostot) TÄRKEÄÄ: Tee sama versionumerointi kaikille etc kansion alla oleville tiedostoille vastaavien MODUULIEN MUKAAN. Eli esimerkiksi {sorsat}/etc/admin vym_admin_1-2-2 Näiden toimenpiteiden jälkeen pitäisi olla valmista itse levitysversion tekoon. Edelliset vaiheen on oltava kuitenkin tehty huolella tai tuloksena voi olla paketti joka sisältää vanhaa koodia! % ant -buildfile distribute.xml ***************************************************** * * * VAROITUS: Ennenkuin ajat tata, niin varmista etta * * kaikki lahdekoodisi on "commit":oitu * * versionhallintaan!!! * * * * HUOM: Admin tai Portal pitaa olla valittu * * leima. Vym version leima valitaan * * automaattisesti admin.properties tai * * portal.properties tieodostosta. * * * * "cvs login" on oltava tehty ennen taman * * ajoa ja CVSROOT ymparistomuuttuja on * * oltava maaritelty. * * * ***************************************************** Usage: ant -buildfile distribute.xml -Dversion=<version number> [ vym_dist admin_dist portal_dist ] -Dversion = Valitsee versionhallinnasta moduulin version. Esim. jos halutaan kaantaa Admin-tyokalun versio 1-2-0, niin parametri annetaan muodossa: -Dversion=1-2-0 HUOM! Ei etuliitetta admin_ tai portal_ mukaan! xxx_dist = Tekee levitykseen tarkoitettavan version valitusta moduulista. Mukaan kopioidaan kaikki tarvittavat kirjastot (itse JRE:ta lukuunottamatta).
16(16) HUOM! admin_dist tai portal_dist hakee automaattisesti myos oikean vym version. Oikea vym versio valitaan etc/admin/admin.properties tai etc/portal/portal.properties tiedostossa. xxx_zip = Paketoi levitysversion yhteen zip tiedostoon. Paketti nimetaan kuten kansio edella lisattyna.zip paatteella (esim. admin_1-2-0.zip). Paketit luodaan zips/ kansioon. Esimerkiksi hallintatyökalun versiosta 1.2.0 tehdään levitettävä ZIP paketti käskyllä: % ant -buildfile distribute.xml Dversion=1-2-0 admin_dist Vaikka paketin tekeminen on hankalaa, niin käytännössä tämä ei ole ongelma, sillä laatuvastaava hoitaa käännösten teon.