Tik-76.115 Versionhallintasuunnitelma

Teletilojen pohjapiirustukset ja telinekuvat (Telkku)

Sisällysluettelo

0. Dokumentin versiot
1. Johdanto
2. Hallittavat tiedostot
3. Tiedostojen nimeäminen
4. Työmenetelmät
5. Mallipohjat
6. Versionumerointi
7. Muutosten hallinta

0. Dokumentin versiot

 
Versio Pvm Muutos Muuttaja
0.1 7.10.1999 Aloitettu Lauri Vuornos
0.2 11.10.1999 Lisätty kuvat hakemistorakenteista Lauri Vuornos
1.0 19.10.1999 Hyväksytty versio (palautuspalaveri 1) Lauri Vuornos
1.1 1.11.1999 Päivitetty hakemistorakenne kuva Lauri Vuornos

1. Johdanto

Tässä dokumentissa kuvataan projektin suunnitelma versionhallinnaksi. Erikseen kuvataan muutoshallinnan prosessi, virheilmoitusten hallinta, versiohallinnan alaiset tiedostot, sekä käytettävä versionhallinta työkalu.

2. Hallittavat tiedostot

Versionhallinnan piiriin kuuluvat kaikki projektin tuottamat tiedostot, joita ei voida johtaa muista tiedostoista. Myös johdetut tiedostot voidaan tarvittaessa ottaa versionhallinnan piiriin. Hallittavat tiedostot voidaan jakaa kahteen osaan: lähdekooditiedostoihin ja dokumentteihin. Lähdekooditiedostoihin kuuluvat kaikki lähdekoodit ja konfigurointitiedostot. Dokumentteihin kuuluvat kaikki projektin tuottamat tekstimuotoiset tiedostot, myös muutospyynnöt ja virheilmoitukset.

3. Tiedostojen nimeäminen

Dokumenttien nimeämisessä noudatetaan selkeää, mutta vapaata nimeämistapaa. Dokumentin nimestä on selvästi käytävä ilmi dokumentin sisältö (esim. projektisuunnitelma.html sisältää projektisuunnitelman). Virheilmoitukset ja muutospyynnöt nimetään juoksevalla numeroinnilla: vi_<nro> ja mp_<nro>, jonka avulla ne linkittyvät virheilmoitusten- ja muutospyyntöjen hallintataulukkoon. Palaverien esityslistat ja muistiot nimetään palvvvvkkpp_n_xx.html, missä vvvvkkpp on palaverin päivämäärä, n on palaverin järjestysnumero sinä päivänä ja xx on joko 'el' (esityslista), 'pk' (pöytäkirja) tai 'ka' (kalvot).

Lähdekooditiedostojen nimeämiskäytäntö tarkennetaan projektin teknisen suunnittelun yhteydessä.

4. Hakemistorakenne

Projektin käyttämän hakemistorakenteen avulla erotetaan toisistaan selkeät kokonaisuudet. Oman kokonaisuutensa muodostavat dokumentit, tietokantaskriptit, konfigurointitiedostot, lähdekooditiedostot, sekä tarvittaessa yhteiskäyttöiset tiedostot, kirjastot ja binääritiedostot. Nämä kokonaisuudet jakautuvat vielä tarvittaessa pienemmiksi osakokonaisuuksiksi.
Kaikki hakemistorakenteen tiedostot kuuluvat versionhallinnan piiriin. Hakemistorakenne pidetään samana versionhallintatyökalussa, sekä projektin henkilöiden työasemilla.


Projektin hakemistorakenne


Dokumenttien hakemistorakenteen tarkempi kuvaus.
 

5. Mallipohjat

Projektin käytössä on tietyt mallipohjat (templates), joita on myös käytettävä. Asiakkaan halutessa projekti voi käyttää myös asiakkaan mallipohjia. Mallipohjat kuuluvat myös versionhallintaan.

5.1 Dokumenttitiedostojen mallipohjat

Dokumenttien mallipohjan tarkoituksena on taata tiettyjen perustietojen olemassaolo joka dokumentissa. Samoin dokumenttien ulkoasu saadaan näin yhdenmukaistettua.

Mallipohjassa on vaadittu seuraavat kokonaisuudet:
- Otsikkokenttä
- Sisällysluettelo
- Dokumentin muutoshistoria
- Johdanto (dokumentin tarkoituksen kuvaus)
- Viitteet muihin dokumentteihin

Dokumentin muutoshistoriaan kirjataan kaikki dokumenttiin tehdyt muutokset ja muutoksen tekijä. Dokumentin tarkoituksen kuvaus tulee olla sellainen, että lukija saa siitä nopeasti kuvan dokumentin sisällöstä. Käytettyjen, mahdollisesti epäselvien termien selitykset ovat kohdassa käytettyjen termien selvitys. Viitteet muihin dokumentteihin sisältää kaikki dokumentin kannalta oleelliset viitteet. Esim. koodikomponentin kuvausdokumentissa on viite lähdekooditiedostoon.

Kokousten esityslistoille ja muistioille on myös omat mallipohjansa, joita käyteään projektin palavereissa.
 

5.2 Kooditiedostojen mallipohjat

Kooditiedostojen kommentoinnissa käytetään JavaDoc:n pohjalta sovellettuja sääntöjä ja konventioita. Tämä mahdollistaa Java-sovellusympäristön työkalun käytön HTML-dokumenttien generoimiseksi kommentoinnista.
Kooditiedostoiden kommentoinnissa vaaditaan kommentointia jokaisen tiedoston alkuun (ns. header-kommentti), jokaiseen funktioon tai aliohjelmaan sekä luokkiin (jos olio-ohjelmointia). Jokaisen tiedoston alussa olevaan header-kommenttiin tulee tiedoston versionumero, nimilista koodin kirjoittajista, selostus tiedoston sisällöstä ja muutoshistoria. Jokaisessa funktiossa on oltava selostus funktion toiminnasta, koodin kirjoittaja, parametrit ja palautusarvot.

Mallipohja kooditiedostoille tarkentuu teknisen suunnittelun yhteydessä.
 

6. Versionumerointi

Projektin tiedostot versioituvat julkaisujen ja revisioinnin tasolla. Tiedoston revisionumero on juokseva numero, joka kasvaa aina muutoksen yhteydessä. Tämä revisiointi koskee kaikkia tiedostoja, dokumentteja ja lähdekooditiedostoja. Revisiointi hoidetaan versionhallintatyökalulla.
Julkaisut ovat yhden tai useamman tiedoston hallinnollisia versioita. tällaisia ovat esimerkiksi dokumenttien  hyväksytyt versiot. Julkaisuun voidaan niputtaa useampia tiedostoja, jotka yhdessä muodostavat kokonaisuuden. Julkaisuun voi kuulua esimerkiksi kaikki yhteen palautukseen kuuluvat hyväksytyt dokumentit tai järjestelmän tietyn julkaisuversion lähdekoodit ja dokumentaatio. Julkaisu tehdään leimaamalla halutut tiedostot versionhallintatyökalulla.

6.1. Julkaisujen nimeäminen

Julkaisujen leimauksessa käytetään vakionimeämistä. Palautukset leimataan PALAUTUS_<n>, missä n on palautuksen numero. Palautuspalaverissa hyväksytyt dokumentit leimataan leimalla KATSELMOINTI_<n>. Palautukseen liittyville dokumenteille päivitetään palautuksen numero dokumentin muutoshistoriaan (major)versionnumeroksi (esim. toisen palautuksen dokumenteille päivitetään versioksi 2.0). Dokumenttien muutoshistoriaan kasvatetaan versionumeroa aina muutoksia tehtäessä (esim. ensimmäinen muutos ensimmäisen palautuksen jälkeen antaa versionumeroksi 1.1).
Järjestelmän versiot (ohjelmakoodi ja dokumentaatio) leimataan eri tavalla riippuen julkaisun kohteesta. Integraatiotestijulkaisut (sisäiseen testiin) leimataan leimalla TELKKU_BL_<versio>, missä <versio> on järjestelmän versionumero. Asiakkaalle toimitettavat julkaisut (myös prototyypit) leimataan leimalla TELKKU_REL_<versio>.

Versionumerointia tarkennetaan tarvittaessa lähdekooditiedostojen ja ohjelmakokonaisuuksien osalta teknisen määrittelyvaiheen aikana.
 

7. Muutosten hallinta

Kaikki muutokset hyväksyttyihin dokumentteihin, määrittelyihin ja suunnitelmiin tehdään keskitetysti. Kaikki muutospyynnöt käyvät läpi muutoshallinta prosessin, jossa muutoksen vaatima työmäärä ja vaikutukset arvioidaan. Tämän analyysin pohjalta tehdään päätös muutospyynnön toteuttamisesta tai toteuttamatta jättämisestä. Muutoshallinta on CCB:n (Change request Control Board) vastuulla, johon kuuluvat projektipäällikkö ja tilanteesta riippuen 1-n muuta projektilaista. Muutospyynnöt tehdään sähköpostitse vakiomuotoisella muutospyyntölomakkeella.

Muutostenhallintaprosessi perustuu kolmen perusroolin vuorovaikutukseen ja muutospyynnön (MP) etenemiseen roolilta toiselle. Nämä kolme roolia ovat muutospyynnön tekijä, CCB ja toteuttajat. Muutospyynnön tekijän roolissa voi olla MP:n tyypistä riippuen asiakas, sovelluskehittäjä tai jokin muu henkilö. CCB:n rooli on muutospyyntöjen hallinnassa täten hyvin keskeinen. Toteuttajan roolissa on henkilö tai ryhmä, joka suunnittelee ja toteuttaa muutospyynnön.

Muutospyynnöllä on ominaisuuksia, joilla erilaiset muutokset, esim. virheilmoitukset, määrittelymuutokset ja kehitysideat, erotetaan toisistaan. Tämän lisäksi MP:n ominaisuudet identifioivat sen yksilöllisesti ja kuvaavat MP:n riittävän tarkalla tasolla. Lisäksi jokaisella MP:llä on tila, jonka avulla eri osapuolet näkevät tietyn MP:n edistymisen muutoshallintaprosessissa.


Muutostenhallintaprosessi

7.1. Virheilmoitusten hallinta

Virheilmoitukset hallitaan muutospyyntöjä vastaavalla tavalla. Kaikki virheilmoitukset tehdään sähköpostitse vakiomuotoisella virheilmoituslomakkeella, jotka tallennetaan osaksi projektin versionhallintaa. Virheilmoituksista pidetään yllä listaa, josta nähdään helposti virheilmoitusten tila ja virheen korjaaja.
 

7.2. Muutospyyntöjen ja virheilmoitusten tallennus

Muutospyynnöt ja virheilmoitukset tallennetaan osaksi projektin versionhallintaa. Virheilmoituksista ja muutospyynnöistä pidetään yllä listaa, jossa on talletettuna tiedot virheilmoituksista ja muutospyynnöistä. Listasta on linkki tarkempaan virheen tai muutospyynnön kuvaukseen. Virheilmoitukset ja muutospyynnöt yksilöidään juoksevalla numeroinnilla.

Muutospyynnöt ja virheilmoitukset tallennetaan samalla tavalla ja niiden käsittely tehdään samalla tavalla. Muutospyynnöistä ja virheilmoituksista pidetään kuitenkin yllä erillistä listaa.

Listassa tulee olla seuraavat tiedot virheestä tai muutospyynnöstä:
- numero
- tila: käsittelemätön, työn alla, hyväksytty, valmis, odottaa
- (havaitsemis)päivämäärä
- (havaitsijan) nimi
- (havaitsijan) sähköpostiosoite
- (havaitsijan) puhelinnumero
- tyyppi: virhe, muutospyyntö, kehitysehdotus
- kohdealue: mihin järjestelmän osaan muutos / virhe kohdistuu
- kiireelisyys
- vaikutus: virheen / muutospyynnön vaikutuksen arvio
- linkki virheen / muutospyynnön tarkempaan kuvaukseen
- päätös toteuttamisesta tai toteuttamatta jättämisestä
- korjaus- / toteutuspäivämäärä
- korjaamiseen / toteuttamiseen käytetty aika
- korjaan / toteuttajan nimi
- tehdyt korjaukset: mihin ja mitä

virheilmoituksen lisäkentät
- sovelluksen versio
- virheen vakavuusaste: vakavuusaste: vakava virhe, haittaa työskentelyä, ei merkittävästi haittaa
- virhee liittyy: toiminnallisuuteen, luotettavuuteen, yhteensopivuuteen, käytettävyyteen, yhdenmukaisuuteen, muuhun (mihin?)
- virheen luokittelu (virheluokat alla)

7.2.2. Virheiden luokittelu

Virheiden luokittelu tehdään kirjan Humphrey, Watts S. A Discipline for Software Engineering. Reading MA: Addison-Wesley
Publishing Company, 1995. pp 48. pohjalta.

Virheluokat:
10  Documentation    comments and messages
20  Syntax                spelling punctuation, typos, instruction formats
30  Build, package    change management, library, version control
40  Assignment         declaration, duplicatenames, scope, limits
50  Interface             procedure calls and references, I/O, user formats
60  Checking            error messages, inadequate checks
70  Data                   structure, content
80  Function             logic, pointers, loops, recursion, computation, function defects
90  System               configuration, timing, memory
100 Environment      design, compile, test or other support system problems