Issue #122: Update documentation in readmes and workflow doc

docs/release3/Arbeidsflyt_3.md

@@ -2,24 +2,32 @@
 
 Som nevnt i arbeidsflyten for release 2 etablerte vi etter første sprint en god vane med å møtes i etterkant av en innlevering for å dele synspunkter rundt gruppens kommunikasjon, samarbeid og forventninger videre. Denne vanen tok vi med oss videre inn i arbeidet med release 3. Etter at vi fullførte release 2, gjennomførte vi en Sprint Review for å evaluere hva vi hadde oppnådd, og for å sikre at alle hadde en felles forståelse av prosjektet så langt. Deretter gjennomførte vi en Sprint Retrospective for å kartlegge hva som gikk bra og hva som kunne blitt gjort bedre. 
 
-Ettersom kravene for release 3 ga oss en nokså høy grad av fleksibilitet til å velge hvordan vi ønsket å videreutvikle applikasjonen, startet vi med å dele tanker rundt dette. Vi ble enige om at i vår situasjon var det mest hensiktsmessig å utvide JavaFX-appen med mer funksjonalitet fremfor å lage en ny klient. Årsaken til dette var fordi vi ønsket å ha all funksjonalitet i et program. I tillegg hadde vi allerede gjort opp noen tanker om hvordan vi ønsket å forbedre funksjonaliteten i javaFX. 
+Ettersom kravene for release 3 ga oss en nokså høy grad av fleksibilitet til å velge hvordan vi ønsket å videreutvikle applikasjonen, startet vi med å dele tanker rundt dette. Vi ble enige om at i vår situasjon var det mest hensiktsmessig å utvide JavaFX-appen med mer funksjonalitet fremfor å lage en ny klient. Årsaken til dette var fordi vi ønsket å ha all funksjonalitet i et program. I tillegg hadde vi allerede gjort opp noen tanker om hvordan vi ønsket å forbedre funksjonaliteten i JavaFX. 
 
-Etter at vi hadde blitt enige om å videreutvikle javaFX-app-en med mer funksjonalitet, var neste steg å diskuterte hva slags funksjonalitet vi tenkte en bruker ønsket for vår applikasjon. Ut i fra denne diskusjonen lagde vi brukerhistorier som skulle kartlegge ulike brukeres behov, og derav hvilken funksjonalitet vi måtte implementere. Som nevnt hadde vi allerede gjort opp noen tanker om hvilken funksjonalitet vi ønsket at sluttresultatet av applikasjonen skulle ha, og tok utgangspunkt i dette når vi laget brukerhistorier. Det var viktig for gruppen å sikre at applikasjonen først og fremst innholdt den mest grunnleggende funksjonaliteten som å legge til og fjerne en vare, og samtidig opprettholde god kodekvalitet. Vi laget dermed en produktkø av brukerhistoriene for å sikre den viktigste funksjonaliteten, før vi bygget videre på applikasjonen. For denne realeasen var oppbygging av REST API noe av det viktigste å få på plass, ettersom den skulle implementeres i ui-klassene. Brukerhistoriene tok derimot utgangspunkt at dette var på plass. 
+Etter at vi hadde blitt enige om å videreutvikle JavaFX-app-en med mer funksjonalitet, var neste steg å diskuterte hva slags funksjonalitet vi tenkte en bruker ønsket for vår applikasjon. Ut ifra denne diskusjonen lagde vi brukerhistorier som skulle kartlegge ulike brukeres behov, og derav hvilken funksjonalitet vi måtte implementere. Som nevnt hadde vi allerede gjort opp noen tanker om hvilken funksjonalitet vi ønsket at sluttresultatet av applikasjonen skulle ha, og tok utgangspunkt i dette da vi laget brukerhistorier. Det var viktig for gruppen å sikre at applikasjonen først og fremst innholdt den mest grunnleggende funksjonaliteten som å legge til og fjerne en vare, og samtidig opprettholde god kodekvalitet. Vi laget dermed en produktkø av brukerhistoriene for å sikre den viktigste funksjonaliteten, før vi bygget videre på applikasjonen. For denne sprinten var utvikling av REST API noe av det viktigste å få på plass, ettersom applikasjonen skulle fungere mot en skytjenesteløsning. Brukerhistoriene tok derimot utgangspunkt at dette var på plass. 
 
-Videre laget vi utviklingsoppgaver tilknyttet de høyst prioriterte brukerhistoriene, og så prioriterte disse. Prioriteringskøen vi lagde sørget for at alle hadde en felles mental modell av veien mot sluttresultatet. I denne iterasjonen hadde vi også et stort fokus på å ikke legge en altfor detaljert plan fremover, men heller reagere på endringer underveis. Dette ga et mer realistisk syn på arbeidsprosessen, og det tillot oss å følge scrums prinsipper. I arbeidet var vi flinke til å jevnlig opprette nye utviklingsoppgaver ut i fra problemer og endringer som oppsto. 
+Videre laget vi utviklingsoppgaver tilknyttet de høyst prioriterte brukerhistoriene, og så prioriterte disse. Prioriteringskøen vi lagde sørget for at alle hadde en felles mental modell av veien mot sluttresultatet. I denne iterasjonen hadde vi også et stort fokus på å ikke legge en altfor detaljert plan fremover, men heller reagere på endringer underveis. Dette ga et mer realistisk syn på arbeidsprosessen, og det tillot oss å følge agile Scrum-prinsipper. I arbeidet var vi flinke til å jevnlig opprette nye utviklingsoppgaver ut ifra problemer og endringer som oppsto.
 
-Vi forstår i etterkant at vi kunne ha laget enda flere utviklingsoppgaver rett etter vi valgte prioriteringen av brukerhistorier, for å sette en tydeligere retning for arbeidet fremover. I tillegg burde vi laget utviklingsoppgavene for brukerhistoriene klare i gitlab, i stedet for å bare skrive dem ned i en egen oversikt. Til tross for dette klarte vi likevel å følge prioriteringen vår ettersom vi som regel satt sammen og jobbet. I tillegg sørget vi for jevnlig "code review" av hverandres kode som bidro til å gi en oversikt over progresjonen. 
+Vi forstår i etterkant at vi kunne ha laget flere mindre utviklingsoppgaver rett etter vi valgte prioriteringen av brukerhistorier, for å sette en tydeligere retning for arbeidet fremover. I tillegg burde vi laget utviklingsoppgavene for brukerhistoriene klare i GitLab, i stedet for å bare skrive dem ned i en egen oversikt. Til tross for dette klarte vi likevel å følge prioriteringen vår ettersom vi som regel satt sammen og jobbet. I tillegg sørget vi for jevnlig "code review" av hverandres kode som bidro til å gi en oversikt over progresjonen. Spesielt gjennomførte vi "code review" ved merginger inn i master-branchen. Dette ble gjort muntlig ved at vi satt ved siden av hverandre, men også ved å benytte kommentarer i "merge requests" på GitLab.
 
-Funksjonaliteten vi ønsket å implementere i denne releasen innebar hovedsaklig muligheten for å fylle på og fjerne varer fra lageret til en "vending machine", og legge til og fjerne "vending machines" fra trackeren. Videre la vi også til et grensesnitt for å skrive inn hvilken server og filnavn trackeren var lokalisert på. Dette gjør det mulig for flere eiere å bruke samme API og applikasjon for å "tracke" sine brusautomater. Ettersom applikasjonen skal være fra en eiers perspektiv, og siden en eier vil nok ikke kjøpe sine egne varer, laget vi et brukergrensesnitt for å fjerne/kjøpe varer, som ville sett likt ut som grensesnittet en faktisk kjøper ville ha brukt. Ettersom en kjøper ikke skal ha mulighet til å gå tilbake til grensesnittet med oversikt over brusautomatene, eller fylle opp varer, la vi også til et grensesnitt der brukeren må skrive inn et passord for å kunne returnere til hovedsiden til applikasjonen. 
+Funksjonaliteten vi ønsket å implementere i denne releasen innebar hovedsaklig muligheten for å fylle på og fjerne varer fra varebeholdningen til en brusautomater, og legge til og fjerne brusautomater fra oversikten/"trackeren". Videre la vi også til et brukergrensesnitt for å skrive inn lokalt filnavn og server-URL. Dette gjør det mulig for flere eiere å bruke samme API og applikasjon for å "tracke" sine brusautomater. Ettersom applikasjonen skal være fra en eiers perspektiv, og siden en eier vil nok ikke kjøpe sine egne varer, laget vi et brukergrensesnitt for å fjerne/kjøpe varer, som ville sett likt ut som brukergrensesnittet en faktisk kjøper ville ha brukt. Ettersom en kjøper ikke skal ha mulighet til å gå tilbake til grensesnittet med oversikt over brusautomatene, eller fylle opp varer, la vi også til et brukergrensesnitt der brukeren må skrive inn et passord for å kunne returnere til hovedsiden til applikasjonen.
 
-Som i release 2, valgte vi å dele inn hovedansvarsområder for arbeidet mellom oss. En av oss fikk hovedansvaret for REST-API- et og gruppemedlemmet som tidligere hadde jobbet med tester fortsatte med det. De to siste som tidligere hadde parprogrammert fortsatte med dette, og jobbet med å øke funksjonaliteten til ui. Vi valgte å parprogrammere denne delen ettersom vi skulle gjøre relativt store endringer, og samtidig knytte gammel og ny funksjonalitet opp mot REST API'et. Denne metoden gjorde det lettere å inspisere og sikre kvaliteten på koden. Det bidro også til at vi i større grad klarte å følge prioritetslisten av oppgaver. En annen fordel med parprogrammering er at begge to fikk en bedre forståelse av hvordan funksjonaliteten til applikasjonen er bygget opp. Dermed kunne begge være til hjelp når testene for ui modulen skulle programmeres. 
+Som i release 2, valgte vi å dele inn hovedansvarsområder for arbeidet mellom oss. En av oss fikk hovedansvaret for REST-API-et og gruppemedlemmet som tidligere hadde jobbet med tester fortsatte med det. De to siste som tidligere hadde parprogrammert fortsatte med dette, og jobbet med å øke funksjonaliteten til det grafiske brukergrensesnittet. Vi valgte å parprogrammere denne delen ettersom vi skulle gjøre relativt store endringer, og samtidig knytte gammel og ny funksjonalitet opp mot et REST API. Denne metoden gjorde det lettere å inspisere og sikre kvaliteten på koden. Det bidro også til at vi i større grad klarte å følge prioritetslisten av oppgaver. En annen fordel med parprogrammering er at begge to fikk en bedre forståelse av hvordan funksjonaliteten til applikasjonen er bygget opp. Dermed kunne begge være til hjelp når testene for UI-modulen skulle utvikles.
 
-Vi opplevde at metoden ved å gi gruppemedlemmene faste ansvarsområder fungerte veldig bra, ettersom det gjorde at hvert medlem ble trygg på å håndtere sin kodedel. Vi var likevel fleksible med å hjelpe hverandre dersom man sto fast med et problem, eller trengte en forklaring på en kodedel. Metoden bidro både med å øke kodekvaliteten, og samtidig gjorde det enklere å samarbeide og ta i bruk funksjonalitet fra andre sin kode. Dette kan på den ene siden ha fungert bra siden vi alltid satt sammen og jobbet, der vi kunne lett spørre hverandre hvis det var noe vi lurte på. Dersom vi ikke hadde sittet sammen og jobbet, kunne denne metoden på den andre siden ha bremset opp progesjonen til tider. Dette er fordi faste ansvarsområdet kan gi mangelfull kompetanse på noen områder, og en må vente på en forklaring av en kodedel hvis det er noe en ikke forstår. Som nevnt ble vi derimot flinke i denne sprinten til å opprettholde en god "code review" i gitlab, og kommentere dersom det er noe kode som man ikke forstår/bør endres. Av denne grunn kunne nok metoden med faste ansvarsområder fungert bra selv om vi ikke hadde sittet så mye sammen og jobbet som vi gjorde.
+Vi opplevde at metoden ved å gi gruppemedlemmene faste ansvarsområder fungerte veldig bra, ettersom det gjorde at hvert medlem ble trygg på å håndtere sin kodedel. Vi var likevel fleksible med å hjelpe hverandre dersom man sto fast med et problem, eller trengte en forklaring på en kodedel. Metoden bidro både med å øke kodekvaliteten, og samtidig gjorde det enklere å samarbeide og ta i bruk funksjonalitet fra andre sin kode. Dette kan på den ene siden ha fungert bra siden vi alltid satt sammen og jobbet, der vi kunne lett spørre hverandre hvis det var noe vi lurte på. Dersom vi ikke hadde sittet sammen og jobbet, kunne denne metoden på den andre siden ha bremset opp progesjonen til tider. Dette er fordi faste ansvarsområdet kan gi mangelfull kompetanse på noen områder, og en må vente på en forklaring av en kodedel hvis det er noe en ikke forstår. Som nevnt ble vi derimot flinke i denne sprinten til å opprettholde en god "code review" i GitLab, og kommentere dersom det er noe kode som man ikke forstår eller mener bør endres. Av denne grunn kunne nok metoden med faste ansvarsområder fungert bra selv om vi ikke hadde sittet så mye sammen og jobbet som vi gjorde.
 
-Et ønske for denne releasen var en mer enhetlig forståelse i gruppen av alt arbeidet som ble gjort. For å sikre dette satt vi faste møtetidspunkter for tiden mot innlevering, slik at vi kunne jobbe så mye som mulig sammen. Da ble det mye lettere å diskutere mulige endringer, og få en bedre oversikt over hva alle jobbet med. Denne fremgangsmåten gjorde det lettere å kommunisere og hjelpe hverandre underveis, som resulterte i mer effektivt arbeid. I tillegg jobbet vi mer sammenhengende på denne releasen, som også økte produktiviteten, og bidro til å styrke vår felles forståelse av alt arbeidet. Hver dag, startet vi med en «Daily scrum» der vi tok opp hvilke endringer alle på gruppen hadde gjort, eventuelle hindringer vi hadde møtt på, og planen for dagen. Dette bidro til et godt teamfokus og en god koordinering av arbeidet. 
+Et ønske for denne releasen var en mer enhetlig forståelse i gruppen av alt arbeidet som ble gjort. For å sikre dette satt vi faste møtetidspunkter for tiden mot innlevering, slik at vi kunne jobbe så mye som mulig sammen. Da ble det mye lettere å diskutere mulige endringer, og få en bedre oversikt over hva alle jobbet med. Denne fremgangsmåten gjorde det lettere å kommunisere og hjelpe hverandre underveis, som resulterte i mer effektivt arbeid. I tillegg jobbet vi mer sammenhengende på denne releasen, som også økte produktiviteten, og bidro til å styrke vår felles forståelse av alt arbeidet. Hver arbeidsdag startet vi med en «Daily Scrum» der vi tok opp hvilke endringer alle på gruppen hadde gjort, eventuelle hindringer vi hadde møtt på, og planen for dagen. Dette bidro til et godt teamfokus og en god koordinering av arbeidet. Vi erfarte at det ville være hensiktsmessig å ta i bruk en kanbantavle for å holde styr på egne og andres arbeidsoppgaver, men vi konkluderte med at det ikke var nødvendig for vår del ettersom vi var et såpass lite team som allerede syntes vi hadde god oversikt over hvor alle andre var i prosessen.
 
-Videre startet vi også en felles praksis for kodevurdering, ved å kommentere i koden på hverandres merge-requests. Det gjorde at det var lettere å identifisere feil, forbedringsmuligheter, og eventuelle brudd på retningslinjer eller beste praksis. Herfra var det også enkelt å opprette utviklingsoppgaver for "bugs" eller forbedringer med en gang. Denne formen for "code review" sikret også økt kunnskap i teamet fordi med kommentarer i selve koden ble det enkelere å forstå hverandres tilbakemeldinger. Kommentarer som pekte på god praksis satte også noen retningslinjer for å opprettholde god praksis videre. 
+Videre startet vi også en felles praksis for kodevurdering, ved å kommentere i koden på hverandres merge requests. Det gjorde at det var lettere å identifisere feil, forbedringsmuligheter, og eventuelle brudd på retningslinjer eller beste praksis. Herfra var det også enkelt å opprette utviklingsoppgaver for "bugs" eller forbedringer med en gang. Denne formen for "code review" sikret også økt kunnskap i teamet fordi med kommentarer i selve koden ble det enkelere å forstå hverandres tilbakemeldinger. Kommentarer som pekte på god praksis satte også noen retningslinjer som var ønskelig å opprettholde videre.
 
 Fra forrige sprint ønsket vi å forbedre og tydeliggjøre utviklingsoppgavene. Dette klarte vi å få til i stor grad for denne iterasjonen ved å lage de mindre og mer konkrete. Mindre utviklingsoppgaver ga klarere retningslinjer for det som skulle gjøres og gjorde dermed oppgavene lettere å prioritere og følge opp. Dette er mer i tråd med den smidige arbeidsmetoden fordi det kan bidra til mer kontinuerlige forbedringer av koden og hyppige oppdateringer i arbeidet.
 
-Til slutt har vi i denne siste releasen sørget for å opprette templates med felles retningslinjer for commit-meldinger, prosessering av utviklingsoppgaver og merge-requests. Disse malene gjorde at vi la mer innsats inn i å skrive gode beskrivelser av hva vi ønsket å oppnå med en utviklingsoppgave, og hva vi hadde oppnådd. Dette tenker vi har talt positivt for løsningene våre. Tidligere hadde vi avklart en felles praksis for dette, men ved å nå ha det skriftlig, ble det lettere for oss å følge en felles standard og heve nivået på arbeidet vårt enda mer. Ved å ha en felles mal for skriving av merge-requests, ble det også lettere å gå gjennom andres merge-requests, som videre økte effektiviteten og kodekvaliteten i arbeidet. 
+Vi kunne dog delt utviklingsoppgavene opp i enda mindre oppgaver. Dette ville gjort at man kan vise til en konkret progresjon når man senere på dagen møtes (f.eks. ved lunsjtider) og skal fortelle om hva man har gjort så langt. En annen fordel ved å dele opp i enda mindre oppgaver (og dermed branches i Git) er at man unngår en masse kluss vi fikk oppleve av å jobbe flere på samme branch. Det ble en del flere merge conflicts og krøll enn det hadde blitt om alle hadde jobbet i hver sin branch. En annen fordel ved å dele opp i enda mindre oppgaver er at det ville fungert bedre ved bruk av kanbantavle for å holde styr på oppgavene i sprinten.
+
+Andre konkrete tiltak vi har gjort for å forbedre arbeidsflyten og kodekvaliteten, og erfaringer vi sitter igjen med:
+- Legge inn kommentaren "// TODO" på steder der man ikke ennå har skrevet ferdig koden, slik at det er lett å finne tilbake til det senere.
+- Hatt en fast prosedyre for når man skal åpne merge requests, der man henter endringer fra master-branchen først og sjekker om alt fortsatt fungerer som det skal. Før vi ble helt konsekvente på dette endte vi noen ganger opp med at master-branchen ikke fungerte som den skulle, noe som er svært uheldig.
+- Blokkert for commits direkte til master-branch, slik at det ikke er mulig å gjøre direkte endringer på master-branchen ved et uhell.
+- Erfart at en branch som ikke lenger brukes, men som skal fortsettes på i en annen branch, må merges inn i denne med en merge request. Hvis det bare hentes endringer fra den branchen som skal slettes, så kan commit-historikken ikke bli like lett å følge.
+
+Til slutt har vi i denne siste releasen sørget for å opprette templates med felles retningslinjer for commit-meldinger, prosessering av utviklingsoppgaver og merge requests. Disse malene gjorde at vi la mer innsats inn i å skrive gode beskrivelser av hva vi ønsket å oppnå med en utviklingsoppgave og hva vi senere hadde oppnådd. Dette tenker vi har talt positivt for løsningene våre. Tidligere hadde vi avklart en felles praksis for dette, men ved å nå ha det skriftlig ble det lettere for oss å følge en felles standard og heve nivået på arbeidet vårt enda mer. Ved å ha en felles mal for skriving av merge requests ble det også lettere å gå gjennom andres merge requests ettersom det fulgte et fast oppsett, som videre økte effektiviteten og kodekvaliteten i arbeidet.