Miten kirjoitetaan selkeä ja hyvä bugiraportti?
ATK-laitteita käyttävät ihmiset ovat varmasti törmänneet tilanteeseen, jossa jokin ei toimi: ohjelmiston painike ei reagoi, sivu jäätyy tai sovellus kaataa tehtävää suorittaessaan koko laitteen. Perinteiset ratkaisuvaihtehdot ovat tietenkin “käynnistä laite/ohjelma uudelleen”, “paina Ctrl + Alt ja Delete” sekä “hae lisää kahvia ja hengitä syvään”. Harvemmin näillä konsteilla kuitenkaan korjataan ongelman juurisyytä.
Jos ohjelmistossa olevaa ongelmaa ei raportoida, siitä ei tiedetä. Silloin sitä ei voi korjata. Näin samat virheet ilmenevät yhä uudelleen ja päästään erään asiakkaan kuvaamaan tilanteeseen: “4-5 työpäivää mennyt hukkaan tämän takia. Kaikenlaisia virheilmoituksia siellä vilisee.”
Hyvän (tai edes keskikohtalaisen) bugiraportin kirjoittaminen ja lähettäminen mahdollistaa sen, että ongelma korjataan ja kaikkien ohjelmiston käyttäjien hermot säästyvät. Tässä artikkelissa käymme läpi, miksi bugiraportointi on tärkeää ja miten kirjoitetaan raportti, josta ohjelmistojen kehittäjät hyötyvät.
Miksi bugiraportointi on tärkeää?
Kehittäjät eivät näe kaikkea. Vaikka sovellusta testataan paljon ennen julkaisua, todelliset käyttötilanteet ja -ympäristöt paljastavat usein uusia ongelmia. Käyttäjillä on erilaisia laitteita, asetuksia, aineistoja ja tapoja käyttää ohjelmaa. Jokaista eri tekijöiden yhdistelmää ei yksinkertaisesti voi ottaa kehitystyössä huomioon.
Toisekseen bugia, josta kehittäjät eivät tiedä, he eivät voi korjata. Kun ongelma raportoidaan selkeästi, se pääsee kehittäjille tutkittavaksi ja korjattavaksi. Ilman raporttia kehittäjät eivät edes tiedä, että ongelma on olemassa.
Kun ongelmat raportoidaan, käyttäjät saavat paremman ja vakaamman ohjelmiston, joka tekee vaaditut tehtävät. Kehittäjät taas saavat tietoa, mitä he voisivat tehdä paremmin, miten ohjelmistoa käytetään ja miten se toimii. Kaikki voittavat.
Miten hyvä bugiraportti kirjoitetaan?
Hyvä raportti vastaa mahdollisimman hyvin kolmeen kysymykseen:
- Mitä tapahtui?
- Missä?
- Miten sen voi toistaa?
Käytännössä bugiraportti alkaa jo otsikosta. “Sovellus ei toimi” on klassinen otsikkovaihtoehto, mutta “QGIS kaatuu kun luon uuden kentän Field Calculatorilla” on huomattavasti kuvaavampi valinta.
Itse leipätekstiin kuvaile kohtaamasi ongelma. Kerro, mitä yritit tehdä, mitä olisi pitänyt tapahtua ja mitä tapahtui. Kerro, toistuuko virhe joka kerta vai satunnaisesti. Hyvä tapa on kirjata ohje ongelman toistamiseksi vaiheittain, esimerkiksi:
- Avaa QGIS.
- Avaa vektoritaso.
- Avaa tason attribuuttitaulukko
- Avaa Field Calculator.
- Valitse “Luo uusi kenttä”.
- QGIS kaatuu.
Yritä kuvata ongelma mahdollisimman yksinkertaisin vaihein ja yksinkertaisessa ympäristössä. Jos saat ongelman toistettua esimerkiksi yksinkertaisella QGIS-projektilla ja yksinkertaisella aineistolla, ei ole syytä lähettää QGIS-projektia, jossa on kymmeniä tasoja ja satoja megatavuja aineistoja.
Jos ohjelmisto tallentaa virhelokia, niin se kannattaa myös liittää bugiraporttiin mukaan. QGISissä virhelokin saa auki ohjelman oikeasta alanurkasta löytyvästä puhekuplasta klikkaamalla. Vaikka sieltä tuleva tekstimassa voi näyttää useimpien silmiin käsittämättömälle, kehittäjälle se kertoo kuitenkin hyvinkin tarkasti, mikä aiheutti ongelman.
Jos epäilet, että ongelma johtuu käyttämästäsi aineistosta, voit myös lähettää sen tai sen osan aineistosta, joka aiheuttaa ongelman.
Lopuksi lisää mukaan tarvittavat tekniset tiedot: yleensä käytetty ohjelmiston versio ja tietokoneesi tai muun käyttämäsi laitteen käyttöjärjestelmä riittävät. Käytännössä siis vaikkapa näin: “käytössä on QGIS 3.40.7. ja Windows 11”.
Halutessasi voit myös ottaa kuvan tai videon ongelmasta liitteeksi. Windows-käyttäjät voivat ottaa ruutukaappauksen painamalla Print screen -näppäintä tai näppäinyhdistelmää Windows-näppäin + Shift + S. Videon kuvaaminen vaatii puolestaan erillisen ohjelman asentamista ja käyttöä. Asiasta kiinnostuneille vinkattakoon ScreenToGif.
Lopuksi
Bugiraportointi ei ole vain kehittäjiä varten, vaan myös raportoijan sekä muiden ohjelmiston käyttäjien eduksi. Bugiraportit auttavat parantamaan ohjelmistoja. Hyvin kirjoitettu raportti vaatii hieman viitseliäisyyttä, mutta säästää jatkossa aikaa, vaivaa ja hermoja. Muotoseikoista ja bugiraportin oikeaoppisuudesta ei kuitenkaan kannata tehdä kynnyskysymystä itselleen – tärkeintä on, että ongelmasta menee tieto eteenpäin. Lisätietoja voidaan kysyä tarvittaessa.
QGISiin liittyvät bugit voi raportoida QGISin GitHub-sivun Issues-osioon. Tämä vaatii kuitenkin GitHub-tunnusten luomisen. Gispon tukipalvelun käyttäjät voivat raportoida FOSS4G-ohjelmistojen bugit ja myös QGISin suomenkielisen käännöksen virheet meille osoitteeseen tuki@gispo.fi. Me voimme korjata ohjelmistoissa esiintyviä ongelmia itse tai kirjata bugiraportit eteenpäin.
