TIMin kehitys tietotekniikan sovellusprojekteissa

Dokumentissa kuvataan ohjelmistokehitykseen ja versiohallintaan liittyvät käytännöt, joita kannattaa noudattaa TIMiin liittyvissä tietotekniikan sovellusprojekteissa.

Käytäntöjä kuvataan lähinnä Jyväskylän yliopiston sovellusprojektien näkökulmasta, mutta ohjeet ovat sovellettavissa myös esimerkiksi kotikoneeseen.

Käytettävät ohjelmistot ja laitteistot

Olennaiset omalle tietokoneelle asennettavat ohjelmat ovat:

• Git
• Jokin VNC-etäpöytäsovellus. Esimerkiksi TigerVNC
• Jos kehität TIMia yliopiston verko ulkopuolella, niin VPN-ohjelmisto
  • Asennus Windowsilla
  • Asennus macOS:ssä
  • Asennus Linuxilla
• Jokin SSH-client. Esimerkisi tavallinen komentoriviltä suoritettava ssh käy.
• Jokin käyttöliittymä myös käy, esim. Putty

Seuraavat eivät ole pakollisia, mutta suositeltavia. Jos esimerkiksi olet tottunut käyttämään Gittiä komentoriviltä tai muun GUIn kautta, niin se käy hyvin.

Jyväskylän yliopiston projektikoneet

Projektin ajaksi TIMin tekniset ohjaajat varaavat ja asentavat projektien jäsenelle kehityskoneet, joihin pääsee VNC-etäyhteydellä.

Tekninen ohja pyytää koneet Jufolta (jf@jyu.fi) seuraavilla spekseillä:

• vähintään 16 GB RAM
• vähintään 100 GB tallennustilaa
• Linux

Tekninen ohjaaja asentaa kehitykseen tarvittavat sovellukset valmiiksi ja jakaa osallistujat eri etäkoneille.

Kun saat oman etäkoneen seuraa nämä ohjeet etäyhteyden ottamiseksi: TIM-etäkehityskoneiden käyttöönotto.

Käytettävät web-sovellukset

TIMin kehityksessä ja dokumentaatiossa käytetään JYU TIM -instanssia. Versiohallintaan suositeltavaa on GitHub, koska TIM-koodi ylläpidetään siellä. Versiohallintaan toki saa käyttää muitakin palveluja, kunhan ne tukevat GIT-repoja.

Projektin aloitus

Yksi projektin jäsenistä tekee (puheenjohtaja/scrum master/pääkoodaaja/yms vastuuhenkilö)

1. Tee uusi organisaatio GitHubiin projektille (tai muuhun GIT-palveluun)

   • GitHub-organisaatiossa voi tehdä hallittuja projekteja ja korttikokonaisuuksia, johon voi esim. koostaa vaatimukset

2. Luo TIM-reposta oman forkkinsa klikkaamalla GitHubissa "Fork"

3. Lisää jäsenet, teknisen ohjaajan ja mahdolliset muut asiantuntijat repoon tai koko organisaatioon Admin-oikeudella.

   Kevään 2025 ohjaajien/asiantuntijoiden GitHub-tunnukset ovat:

   • vesal (Vesa Lappalainen)
   • dezhidki (Denis Zhidkikh)
   • sijualle (Simo Lehtinen)
   • saviit (Sami Viitanen)

4. Ilmoita projektiorganisaatiolle forkin osoite, jotta he voivat päivittää oman lokaalin TIMin repo-osoitteen

Tekninen ohjaaja tekee

Viimeistään kun projektin nimi on selvillä, ohjaaja luo TIMiin projektille

• TIM-ryhmän hakemistoon groups/tieprojektit
• Viestilistan, jolle laitetaan seuraavat asetukset:
  • Viestilistalle saa lähettää liitteitä
  • Viestilistan viestin vastaanottaja on viestilista (ns. munging)
  • Viestilistan ulkopuoliset saavat lähettää viestejä listalle
  • Viestilistan jäsenenä on ylempänä luotu TIM-ryhmä
• Projektikansion hakemiston kurssit/tie/proj

Ohjaaja antaa tarvittaessa myös oikeudet lukea ja kopioida (pohjaksi) jonkin aiemman TIM-projektin materiaalia.

TIMin kehitysdokumentaatio

TIMin kehitykseen liittyvä dokumentaatio on hakemistossa TIMin kehitys, jossa tämäkin dokumentti sijaitsee. Osa dokumenteista on kuitenkin vanhentuneita, minkä vuoksi sellaisia ei kannata lukea kovin tarkkaan.

Alla on lista dokumenteista, jotka ainakin ovat ajantasaisia:

Asennus ja ylläpito:

• TIMin asentaminen
• PyCharm
• Järjestelmäarkkitehtuuri
• Johdatus TIMin kehitykseen

Koodaus:

• Koodikäytänteet
• Testaaminen
• Ohjelmointikielet ja kirjastot
• TIMin ohjelmointikielet demojen kautta

Muut:

• TIM-perehdytys 2024
• TIM-perehdytys 2023
• TIM-perehdytys 2022
• TIM-perehdytys 2021
• TIM-perehdytys 2019
• Aikaleimat
• Ylläpitäjien toimintoja
• Kirjastot

Projektien koneisiin liittyviä ongelmia ja ratkaisuja

Alla on lueteltu muutamia eteen tulleita ongelmia koskien kehitysympäristön asennusta ja käyttöä, etenkin projektihuoneiden koneilla.

Kehityskoneen käyttäminen tulosten esittämiseen

Vuodesta 2024 lähtien projektien kehityskoneet ovat avoinna yliopistoverkossa. Riittää, että kehityskoneessa käynnistää TIM-palvelimen, jolloin TIM on saatavilla yliopiston verkon sisältä osoitteesta webapp0N.it.jyu.fi, missä N on omaa konetta vastaava numero.

Etäyhteyden ottaminen projektihuoneen koneeseen

Seuraa ohjetta TIM-etäkoneiden käyttöönotto.

Omistajatietojen kirjaaminen lähdekoodiin

Sovellusprojekteissa tehdään lisenssisopimus, jossa määritetään ehdot, jolla ryhmä luovuttaa lähdekoodinsa TIM-projekteille. Yleensä lisenssiksi on sovittu MIT ja koodin "omistajuus" ei luovutettu täysin TIM-projektille. Käytännössä tämä tarkoittaa, että projektien aikana tuotettuihin lähdekooditiedostoihin lisätään tekijätiedot sekä viite tiedoston lisenssiin.

Python-koodissa tekijätiedot kirjataan tiedoston alkuun (ennen importteja) esimerkiksi seuraavasti:

"""
Short description of Python module
"""

__authors__ = [ "Matti Meikäläinen", "Maija Meikäläinen" ]
__license__ = "MIT"
__date__ = "11.4.2022"

TypeScript-koodissa tekijätiedot kirjataan tiedoston alkuun esimerkiksi seuraavasti:

Jokainen projektiorganisaatio päättää itse, kirjataanko tiedoston tekijät tai kaikki projektin jäsenet.

Jos lähdekooditiedosto on alun perin TIM-järjestelmän omaa koodia, mutta projektin aikana tiedoston sisältöä on muokattu merkittävästi, lisätään tiedoston alkuun omistajatiedot yllä mainitulla tavalla. Siinä tapauksessa projektin jäsenten lisäksi listaan tulevat tiedoston aiemmat tekijät ja muokkaajat.

Täydellisen listan tiedoston tekijöistä saa helpointen git-työkalulla:

Tiedoston luontipäivämäärän saa komennolla

git log --follow --format=%ad --date default tiedostonpolkutähän | tail -1

Lähdekoodien tulostaminen

Idea: luodaan lähdekoodeista yksi iso markdown-tiedosto, jossa sisältönä on kutakin tiedostoa kohden tiedoston polku ja sisältö. Viedään tiedosto TIMiin ja tulostetaan se PDF:nä.

Lähtökohtaisesti lähdekoodin tulostus kannattaa tehdä vasta silloin, kun tekninen ohjaaja on hyväksynyt sen. Joka tapauksessa tulostus kannattaa tehdä sillä koneella, jolla projekti kehitettiin. Mikäli teet sen jollain toisella koneella, kloonaa ensiksi koneellesi teidän projektin päähaara (yleensä master).

Markdown-tiedoston luonti

Aja alla olevat komennot Unix-koneeella, mikäli mahdollista.
Muussa tapauksessa (Windows + GIT Bash tai Windows + MinGW), asenna Python 3.

0. Mene TIM-projektiisi hakemistoon (yleensä /opt/tim)

1. Varmista, että sinulla on uusin projektin master-haara. Tarvittaessa aja git pull.

2. Lisää TIM-projektin etäosoite GITiin:

   git remote add tim https://github.com/TIM-JYU/TIM.git

3. Lataa kaikki TIMin haarat:

   git fetch tim

4. Aja

   curl -s https://tim.jyu.fi/print/tim/TIMin-kehitys/skriptit/koodilistaus.py | python3 - tim/master master

Tämä luo neljä tiedostoa repon juureen:

• added.md -- sisältää kaikki projektissa lisätyt tiedostot
• modified.md -- sisältää kaikki projektissa muutetut TIM-lähdekooditiedostot
• added_files.txt ja modified_files.txt -- sisältävät listauksen kaikista mukaan otetuista tiedostoista

Jos repoon on lisätty projektin aikana muutakin kuin tekstitiedostoja, niin ne on suodatettava pois. Avaa added_files.txt ja modified_files.txt ja poista ne tiedostorivit, jotka haluat ottaa mukaan koodilistaukseen.

Tämän jälkeen nimeä tiedostot nimillä added_files_skip.txt ja modified_files_skip.txt.

Aja sitten vaiheen 4. komento uudelleen.

Dokumentin vienti TIMiin

Luo TIM-dokumentti, mene Manage-näkymään ja liitä dokumentin sisällöksi added.md:n sisältö.

Luo toinen TIM-dokumentti ja tee sama modified.md:lle.

Dokumentin tulostus

Mene dokumentin View-näkymään. Ensimmäinen lataus saattaa kestää hetken, koska TIM hake tiedostojen sisällöt versiohallinnasta.

Valitse vasemmasta valikosta rattaan kuva ja Print Document. Varmista, että valittu template on runko ja Output format on PDF. Klikkaa Create.

Teknisille ohjaajille

Alla muutama vinkki sovellusprojektin teknisille ohjaajille.

Projektin repon ajan tasalla pitäminen

Pidä projektin repo ajan tasalla TIMin päärepon kanssa. Toisin sanoen:

• jos projekti ei ole vielä tehnyt committeja omaan haaraansa, niin puske TIMin päähaaran commitit sinne normaalisti
• muussa tapauksessa mergeä TIMin päähaara projektin haaraan

Voit antaa lyhyen ilmoituksen asiasta projektin sähköpostilistalla aina kun päivityksiä on tullut.

Se, miten usein tätä kannattaa tehdä, riippuu toki siitä, kuinka paljon TIMin päähaaraan tulee muutoksia projektin aikana. Pienien bugikorjausten takia ei tarvitse, mutta jos esim. iso määrä tiedostoja siirtyy paikasta toiseen, niin sellainen on järkevää päivittää. Samaten isommat refaktoroinnit.

Lähdekoodin katselmointi

Lähdekoodin katselmointi sujunee parhaiten tekemällä Pull Request (PR) sovellusprojektin GitHub-forkin päähaarasta TIMin päähääraan. Eli Pull Request -teossa asetetaan:

• head repository -repoksi projektin forkki,
• compare-haaraksi projektin päähäära,
• base repository -repoksi TIM-JYU/TIM ja
• base-haaraksi master-haara.

PR kannattaa merkitä keskeneräiseksi (eli jättää Draft-tilaan) kunnes projekti on valmis:

Projektin valmistuessa PR voidaan mergetä suoraan TIMiin.

Aina kun yhden erän katselmointikommentteja julkaisee, kannattaa vielä lopuksi laittaa erillinen kommentti PR:ään, jossa pingaa kaikki projektin jäsenet (ei @all, koska se pingaa kaikki TIM-projektin jäsenet).

Koodia kannattaa katselmoida "jatkuvalla tahdilla" heti kun sitä alkaa tulemaan, jolloin "junan suunnan muuttaminen" on tarvittaessa helpompaa. Vanhanaikaista katselmointitapaa ei kannata käyttää, eli että odottaisi, kunnes sovitaan koodikatselmointitilaisuus ja vasta sitten rupeaisi katselmoimaan. Maailma ei kutenkaan kaadu jos PRää ei tehdä heti projektin alussa, koska alussa oikeasti katselmoitavaa on vähän. Viimeistään jatkuvaa katselmointia kannattaa aloittaa ensimmäisen katselmointitilaisuuden jälkeen.

Katselmointitilaisuus on sitten lähinnä katselmoijan jättämien kommenttien läpikäyntiä ja projektilaisten mahdollisiin kysymyksiin vastaamista.