⚠️ Viikon tehtävien palautuksen deadline on tiistai 3.12. klo 23:59. Tehtävät on tarkoitus tehdä joko pajassa tai omatoimisesti.

Tehtävät palautetaan GitHubin avulla Labtooliin rekisteröimääsi repositorioon. Muista pushata tehtävät GitHubiin ennen palautuksen deadlinea! Klo 00 jälkeen tulevia repositorion päivityksiä ei huomioida pisteytyksessä, eli ne tuovat 0 pistettä.

Palautuksesta saadut pisteet ja palaute löytyy Labtoolista viimeistään deadlinea vastaavan viikon loppuun mennessä. Muista tarkistaa saamasi pisteet ja palaute. Jos pisteytyksestä herää kysymyksiä, lähetä viesti Labtoolin kautta.

Tämän viikon harjoitustyön palautuksesta on tarjolla 3 pistettä.

GitHub release

Eräs tapa julkaista ohjelmasta vakaa versio on tehdä GitHubiin release, eli julkaistu versio:

  • Klikkaa repositorion GitHub-sivulta kohtaa “Releases”
  • Valitse Create a new release
  • Määrittele julkaisun tiedot
    • Käytä tagina palautuksen viikkoa. Esimerkiksi viikon 5 palautuksessa tagina on “viikko5”
  • Jos sovelluksen suorituksessa edellytetään tiedostoja, tai jonkin erityisen komennon suorittamista, voit mainita niistä tekstissä. Kaikki asennukseen vaadittavat toimenpiteet tulee kuitenkin mainita myös README.md-tiedostossa
  • GitHub liittää automaattisesti projektin lähdekoodin zip-pakattuna releaseen.

Release

Nyt koodi on kenen tahansa ladattavissa menemällä GitHub-repositorioosi, ja klikkaamalla repositoriosivusi kohtaa “1 release”. Ohjelman käynnistäminen tulee olla mahdollista lataamalla releasessa oleva projektin lähdekoodi ja noudattamalla README.md-tiedoston ohjeita.

Projektin käyttöönottoa kannattaa testata releasen kautta: lataa releasessa mukana oleva lähdekoodi, noudata oman README.md-tiedostosi ohjeita ja varmista, että sovellus toimii, kuten pitäisi. Älä oleta mitään, esimerkiksi, että käyttäjä tietää, että tiettyyn hakemistoon tulee lisätä tietty tiedosto, että sovellus toimii.

Issueiden salliminen GitHubissa

Varmista, että palautusrepositorioosi on mahdollista tehdä issueita, eli repositorion Settings näyttää seuraavalta

Harjoitustyö

Tämän viikon aikana harjoitustyöhön toteutetaan edellisen viikon tapaan uutta toiminnallisuutta ja parannetaan sen dokumentaatiota.

Tämän viikon harjoitustyön palautuksesta on tarjolla 3 pistettä. Viikkopisteiden lisäksi kannattaa pitää mielessä harjoitustyön lopullisen palautuksen arvosteluperusteet.

Harjoitustyö 1: GitHub release

Tee projektistasi GitHub release edellä esitetyn ohjeen mukaisesti (0.25p):

  • Release sisältää ohjelman uusimman version lähdekoodin (GitHub lisää tämän automaattisesti releasen tehdessä)
  • Releaseen on linkki projektin README:stä

Harjoitustyö 2: Koodikatselmointiin valmistautuminen

Jotta voit osallistua viikolla 6 pidettävään koodikatselmointiin (josta on tarjolla 2 kurssipistettä), tulee seuraavien asioiden olla kunnossa:

  • Viikon 5 deadlinen jälkeen tulee palautusrepositoriosta löytyä toimiva versio harjoitustyöstä, joka toteuttaa osan määrittelydokumentin käyttäjälle näkyvästä toiminnallisuudesta
  • Viikon 5 palautuksesta tulee saada enemmän kuin 0 pistettä
  • Palautusrepositorioistasi on GitHub-issuet sallittuna

Harjoitustyö 3: Uutta toiminnallisuutta

Kasvata ohjelmaa edellisestä viikosta (0.75p):

  • Ohjelman pystyy suorittamaan komentoriviltä komennolla poetry run invoke start
  • Suoritettava versio on kasvanut edellisestä viikosta ja toteuttaa edellisen viikon versiota suuremman osan määrittelydokumentin toiminnallisuuksista eli ohjelmaan on lisätty jotain käyttäjälle näkyvää hyödyllistä toiminnallisuutta
  • Merkitse lisäksi tarkastusta varten määrittelydokumenttiin valmiit toiminnallisuudet “tehty” merkinnällä

Ohjeita toteutukseen löydät täältä.

Harjoitustyö 4: Testaaminen

Edistä ohjelman testaamista (0.5p):

  • Sovellukselle tulee pystyä generoimaan testikattavuusraportti komennolla poetry run invoke coverage-report
  • Projektin juurihakemistossa tulee olla .coveragerc-tiedosto, jossa määritellään, mistä hakemistosta testikattavuus kerätään. Käyttöliittymään ja testeihin liittyvä koodi jätetään testikattavuusraportin ulkopuolle
  • Projektin src-hakemiston alahakemistoissa tulee olla tyhjät __init__.py-tiedostot ohjeiden mukaisesti, jotta kaikki halutut tiedostot sisällytetään testikattavuusraporttiin
  • Ohjelman testien haarautumakattavuuden tulee olla vähintään 40%
  • Testien tulee olla mielekkäitä, eli niiden on testattava jotain ohjelman kannalta merkityksellistä asiaa

Harjoitustyö 5: Koodin laatu

Kiinnitä koodin laadussa huomio seuraaviin seikkoihin (1p):

  • Sovelluslogiikka on riittävissä määrin eriytetty käyttöliittymästä
  • Ohjelman rakenne heijastaa ohjelman loogista rakennetta ja on nimennältään järkevä
  • Pylint-virheitä on alle 5

Harjoitustyö 6: Dokumentaatio

Lisää dokumentaatioon ainakin yksi jotain oleellista toiminnallisuutta kuvaava sekvenssikaavio (0.5p):

Harjoitustyö 7: Changelog

Dokumentoi viikon aikana sovellukseen tehdyt merkittävät muutokset edellisen viikon tapaan dokumentaatio-hakemiston changelog.md-tiedostoon. Mallia voi ottaa referenssisovelluksesta.

HUOM: Changelog-merkinnän puuttuminen johtaa merkittävään pistevähennykseen.

Harjoitustyö 8: Pistevähennykset

Seuraavien kohtien puutteet vähentävät pisteitä:

  • Koodin laatu
    • Rakenne on järkevä (esim. kaikki koodi on samassa hakemistossa)
    • Sovelluslogiikkaa on eriytetty riittävästi käyttöliittymästä
  • Tuntikirjanpito on ajantasalla
    • Tuntien summan tulee olla merkittynä
    • Tuntikirjanpitoon ei merkitä laskareihin käytettyä aikaa
  • Viikolle on tehty changelog-merkintä changelog.md-tiedostoon
  • Palautusrepositorioosi voi tehdä GitHub-issueita, katso ohje
  • Repositorion README.md-tiedosto on kunnossa
    • Tiedosto on kurssin tämän vaiheen osalta relevantin sisällön suhteen samankaltainen kuin referenssisovelluksen README.md, eli siellä on ainakin seuraavat
      • Harjoitustyön aiheen lyhyt kuvaus
      • Linkit vaatimusmäärittelyyn, arkkitehtuuridokumenttiin ja tuntikirjanpitoon
      • Linkki releaseen
      • Ohjeet komentoriviltä suoritettaviin toimenpiteisiin (ohjelman käynnistys, testaus, testikattavuusraportin suoritus, pylint-tarkistuksien suorittaminen)
  • Repositorio siisti
    • Ei ylimääräistä tavaraa (mm. pytest- ja coverage-komentojen generoimia tiedostoja)
    • Laskarit jätetään hakemiston laskarit alle
    • Järkevä .gitignore-tiedosto olemassa

Harjoitustyön toimivuus

HUOM: Saadaksesi harjoitustyöstä viikkokohtaiset pisteet, sovelluksen tulee toimia laitoksen tietokoneella ja ohjaajien pitää pystyä se niiltä aukaisemaan! Voit testata tätä millä tahansa Cubbli-tietokoneella, kuten fuksiläppärillä, tai laitoksen tietokoneluokkien tietokoneilla. Testaus onnistuu myös virtuaalityöasemassa joko selaimen tai VMWare Horizon -asiakasohjelman avulla.

Virtuaalityöasemassa oman sovelluksen testaaminen onnistuu selaimen avulla seuraavasti:

  1. Kirjaudu virtuaalityöasemaan ja valitse Cubbli Linux
  2. Käynnistä terminaali ja tarkista käytössäoleva Python-versio komennolla python3 --version. Jos versio on alle 3.8, päivitä versio tämän ohjeen avulla
  3. Varmista, että Poetry on asennettu suorittamalla komento poetry --version. Jos asennus puuttuu, seuraa näitä Linux-asennuksen ohjeita
  4. Kloonaa repositoriosi haluamaasi hakemistoon git clone-komennolla
  5. Siirry repositoriosi hakemistoon ja asenna riippuvuudet komennolla poetry install. Huomaa, että komento tulee suorittaa hakemistossa, jossa pyproject.toml-tiedosto sijaitsee

Mikäli yhteys virtuaalityöasemaan pätkii, kannattaa kokeilla toista selainta. Käyttäjät ovat raportoineet ainakin Google Chromen toimivan varsin hyvin. Myös VMWare Horizon Clientin asentaminen saattaa auttaa.

HUOM: Jos suoritat SQLite-tietokantaa käyttävää sovellusta virtuaalityöasemassa, saatat törmätä virheeseen database is locked. Ongelma ratkeaa luultavasti tämän ohjeen avulla.

Älä plagioi tai riko tekijänoikeuksia

Plagiointi

Kurssilla seurataan Helsingin yliopiston opintokäytäntöjä. Plagiarismi ja opintovilppi, eli esimerkiksi netissä olevien tai kaverilta saatujen vastausten kopiointi ja niiden palauttaminen omana työnä on kiellettyä. Todettu opintovilppi johtaa kurssisuorituksen hylkäämiseen ja toistuva opintovilppi voi johtaa opinto-oikeuden määräaikaiseen menettämiseen.

Mitä plagiointi tarkoittaa harjoitustyön yhteydessä? Koodin suora kopioiminen on kiellettyä poikkeuksena muutaman rivin mittaiset algoritmit ja ChatGPT:n tai vastaavien välineiden generoima koodi (ks. alla). Myös koodin rakenteen suora kopioiminen esim. siten että muuttujien ja funktioiden nimet muutetaan lasketaan plagioinniksi. Toisaalta esim. verkosta löytyneitä kuvia saa käyttää, jos tähän on oikeus (ks. kohta tekijänoikeudet), mutta näin tehtävessä tulee työn dokumentaatioon tehdä “lähdeviite”, eli mainita mistä lainaus on tehty.

Samat plagiaattisäännöt koskevat työn dokumentaatiota ja erityisen kiellettyä on copy pasteta referenssisovelluksen dokumentaatiota.

ChatGPT ja vastaavat

Myös ChatGPT:n ja vastaavien tekoälyyn perustuvien välineiden (kuten esim. Microsoft Copilotin, Google Geminin, CurreChatin tai GitHub Copilotin) generoiman koodin tai tekstin esittäminen itse kirjoitetuksi on plagiointia. Generoidun koodin käyttö on kurssilla sallittua, mutta “ympäröi” aina tällainen koodi kommenteilla # generoitu koodi alkaa ja # generoitu koodi päättyy. Tee näin myös silloin, jos olet tehnyt generoituun koodiin vain vähäisiä muutoksia (vaihtanut muuttujien ja funktioiden nimiä tms.). Toisaalta, jos tämä ei käyttötavasta johtuen tunnu mielekkäältä, voit vaihtoehtoisesti liittää dokumentaatioon kuvauksen siitä, että millä tavoin ja missä laajuudessa olet tekoälypohjaisia välineitä harjoitustyösi missäkin osassa käyttänyt.

Muistathan, että ChatGPT:n ja vastaavien välineiden käyttö yksikkötestien koodin generointiin on kurssilla kiellettyä (muuten saa kyllä käyttää testailtaessakin).

Tekijänoikeudet

Kunnioita muutenkin tekijänoikeuksia ja muita immateriaalioikeuksia. Muista, että et saa käyttää mitä tahansa verkosta löytynyttä omassa työssäsi. Tämä koskee monenlaista materiaalia ohjelmakoodista kuviin ja teksteihin. Tarkista siis aina, että onko käyttö sallittua sen lisenssin mukaan, jolla materiaali mahdollisesti on jaettu. Muista, että harjoitustyöt ovat lähtökohtaisesti julkisia GitHubissa. On omalla vastuullasi, ettet riko tekijänoikeuksia.