lectures/.gitignore

@@ -2,4 +2,4 @@
 .gradle
 
 # Ignore Gradle build output directory
-build
+build/

lectures/README.md

+# Materiale laget med asciidoctor
+
+Mappa **asciidoctor** inneholder tekstlig materiale, mens **revealjs**-mappa
+inneholder lysarkene. 
+
+## Hvordan bygge
+
+Bygging av både dokumentasjon og lysark skjer med gradle.
+
+Bruk `gradle asciidoctor` for å generere HTML for det tekstlige og `gradle asciidoctorRevealJs` for lysarkene.
+Konvertering kan også gjøres med den generelle `gradle build`.

lectures/asciidoc/README.adoc

-== Multi-eksempel
-
-Dette eksemplet viser hvordan rigger et multi-prosjekt med gradle,
-med del-prosjekter for
-
-- domenelogikk (core)
-- brukergrensesnitt med JavaFX og FXML (fx)
-- React-basert web-klient (react)
-- web-server med JAX-RS og Jersey (jersey)
-
-=== Bygging med Gradle
-
-https://docs.gradle.org/current/userguide/userguide.html[Gradle] er et såkalt byggesystem, som automatiserer oppgaver knyttet til utvikling og kvalitetssikring av programvare, f.eks.
-kompilering, kjørings av enhetstester og integrasjonstester, konvertering av dokumentasjon til HTML, pakking som kjørbart program, osv.
-Det finnes teknisk sett ikke grenser for hva et byggesystem kan gjøre, generelt handler det om å automatisere bort alt praktisk fikkel,
-som ellers hindrer en å jobbe effektivt.
-
-Det finnes flere byggesystem, de viktigste i Java-verdenen er https://maven.apache.org[Maven] og Gradle, mens Javascript-verdenen har sine, bl.a. https://docs.npmjs.com[npm].
-I dette prosjektet har vi valgt å bruke Gradle, fordi det er enklere å skrive og lese oppsettet og trigge kjøring, mer fleksiblet og
-det vi ønsker å automatisere i akkurat dette prosjektet er innafor det Gradle håndterer godt. For andre Java-prosjekter https://phauer.com/2018/moving-back-from-gradle-to-maven/[kan Maven være et bedre alternativ].
-Siden ett av prosjektet bruker Javascript og npm, så
-bruker vi et eget Gradle-tillegg som bygger bro til npm. 
-
-Gradle er bygget rundt tre sentrale elementer:
-
-- oppgaver (tasks) - det som automatiseres, f.eks. kompilering, kjøring av tester, osv.
-- prosjekter - enhetene som oppgaver utføres innenfor
-- tillegg (plugins) - angir hvilke oppgaver som hører til et visst type prosjekt.
-
-Oppsettet for bygging består bl.a. i å angi hvilke (del)-prosjekter som inngår i hovedprosjektet,
-hvilke avhengigheter det er til eksterne moduler og mellom prosjektene, hvilke tillegg som bør aktiveres for disse prosjektene
-(basert på hva slags type prosjekt det er) og hvordan hver type oppgave skal konfigureres.
-
-NOTE: Det litt spesielle med Gradle er at filene for å sette opp et Gradle-bygg egentlig er https://docs.gradle.org/current/userguide/groovy_build_script_primer.html[kode skrevet i det Java-lignende språket Groovy].
-Koden brukes primært til konfigurasjon, altså bygge opp beskrivelsen av oppgavene,  prosjektene og tilleggene og. API-et er utformet slik at koden skal se deklarativ ut.
-En kan flette inn vanlig kode også, hvis en skjønner litt om hvordan API-et virker. Dette gir enorm fleksibilitet, men kan også gjøre filene vanskelige å forstå.
-
-De to viktigste filene for å sette opp et Gradle-bygg er *settings.gradle* og *build.gradle*.

lectures/asciidoc/gitpod.adoc

+= Gitpod
+
+link:slides/gitpod.html[Lysark]
+
+== Problemet som gitpod løser
+
+Rigging av alt som trengs for utvikling tar mye tid. En skal installere _språket_ (*python*, *java*, ...) og en trenger diverse _rammeverk_ (*junit*, *javafx*, ...). Kanskje skal en bruke såkalte _byggeverktøy_ (*maven*, *gradle*, ...) og det må installeres og konfigureres. På toppen av dette kommer selve _IDE-en_ (*VSCode*, *IntelliJ*, *Eclipse*, ...), som må passe til og være konfigurert for det en har installert forøvrig.
+
+En kompliserende faktor er _versjoner_, en må ha versjoner av alt som passer sammen og ofte trenger en ulike versjoner for ulike prosjekter. Selv om det finnes verktøy som *sdkman* som hjelper en å installere og veksle mellom ulike versjoner, så er det en del manuelt arbeid.
+
+For større prosjekter er kanskje ikke dette merarbeidet så problematisk, det må jo ikke gjøres så ofte. Men hvis en veksler mellom flere mindre prosjekter eller bare skal jobbe med små eksempler og øvinger, så kan det bli veldig tungvint.
+
+== Gitpod = VSCode + git + Docker
+
+Gitpod prøver å løse dette problemet ved å tilby en nettleserbasert IDE (*VSCode*), som er ferdigkonfigurert for spesifikke prosjekt. En slipper dermed å installere IDE-en. Konfigurasjonen av både IDE-en og den underliggende _virtuelle maskina_ (*Linux* i *Docker*) ligger i *git*-kodelageret sammen med prosjektfilene forøvrig. Når kodelageret med konfigurasjon og prosjekfiler først er satt opp, så slipper en dermed også å installere språk, rammeverk og verktøy, det er bare å åpne IDE-en med utgangspunkt i kodelageret.
+
+Jobben med oppsett må jo fortsatt gjøres, men en trenger bare å gjøre det én gang. Alle som siden skal jobbe med samme prosjekt, kan bare åpne IDE-en på et kodelager og gå i gang. Dersom det er snakk om et kode-eksempel, en øving eller et standardisert prosjekt, så kan det gjøres på forhånd av fagstaben, så i hvert fall studenten slipper styret med å sette alt opp. Og for nye prosjekt kan en ofte ta utgangspunkt i tidligere prosjekter eller eksempler basert på samme språk og rammeverk.
+
+== Gitpod @ NTNU
+
+Gitpod har integrasjoner med skytjenester som *gitlab* og *github*, så en kan logge inn på og administrere kodelagre der. Gitpod kan også settes opp internt, og NTNU har sin egen gitpod-installasjon tilgjengelig på http://gitpod.stud.ntnu.no, som er integrert med IDI sin *gitlab*-tjeneste på http://gitlab.stud.idi.ntnu.no, så emner som bruker gitlab kan automatisk tilby gitpod som plattform for utvikling.
+
+Alle kodelagre i IT1901 med eksempler og maler er ferdig _gitpodifisert_, se f.eks. https://gitlab.stud.idi.ntnu.no/it1901/javafx-templates[javafx-templates]. Dermed er de lette å bygge videre på, det er bare å trykke på *Gitpod*-knappen. Faktisk kan alle kodelagre på vår gitlab åpnes i gitpod for redigering av filer. Men for å kunne utvikle ordentlig, så må de altså gitpodifiseres vha. konfigurasjonsfilen *.gitpod.yml* og evt. en tilhørende *docker*-fil.
+
+En alternativ måte å åpne gitpod på er å skrive inn nettadressen til gitpod-tjeneren (http://gitpod.stud.ntnu.no) etterfulgt av *#* og så adressen til gitlab-kodelageret som skal åpnes, f.eks. `http://gitpod.stud.ntnu.no#https://gitlab.stud.idi.ntnu.no/it1901/javafx-templates`.
+
+== Gitpod-arkitektur
+
+VSCode i nettleseren fungerer nokså likt VSCode lokalt, den har tilgang til et filsystem med kjørebare programmer, og en del av filsystemet utgjør arbeidsområdet til VSCode. Forskjellen er at filsystemet og programmene er inni en virtuell maskin i skyen, og maskina startes opp kun for å kjøre VSCode i nettleseren. Ved oppstart _klones_ kodelageret inn i maskina, og innholdet utgjør altså arbeidsområdet til VSCode. Konfigurasjonen av maskina og evt. oppstartsinstruksjoner leses ut av *.gitpod.yml* på toppnivå i det samme kodelageret.
+
+image::images/gitpod-arch.png[width=800]
+
+Den virtuelle maskina er _flyktig_, i den forstand at den forsvinner av seg selv hvis en lukker VSCode (eller fanen) eller lar være å bruke den en periode. Arbeidsområdet (og noen andre viktige filer) arkiveres imidlertid, slik at den kan startes opp igjen med i praksis samme innhold. Det blir som om en legger en bærbar i dvale og så vekker den til live igjen. Vanligvis vil en derfor fortsette med et eksisterende arbeidsområde fra hovedsiden til gitpod-tjenesten, i stedet for å starte en ny virtuell maskin med et nytt arbeidsområde fra (gitlab-nettsida for) kodelageret. Det er bare når en endrer oppsettet etter å ha redigert *.gitpod.yml* eller *docker*-fila at en må starte en helt ny maskin. 
+
+Hvis den virtuelle maskina er riktig satt opp (se under om konfigurering med *.gitpod.yml*), så kan en faktisk kjøre grafiske apper (f.eks. skrevet i JavaFX) og få dem vist inni gitpod eller i et separat nettleservindu. Dette krever at en "slår på" en virtuell grafisk skjerm som er en del av den virtuelle maskina. Se etter tallet 6080 i statuslinja nederst og trykk på det. Da spretter det opp et panel og en kan angi at 6080 (som representerer den virtuelle grafiske skjermen) skal vises i *Preview*-panelet eller i et eget nettleser-vindu.
+
+== Gitpod-bruk i emner
+
+Gitpod kan brukes i emner på ulike måter. Emner som i dag distribuerer og deler innhold vha. git-kodelagre, kan gitpodifisere og få ekstra fordeler. Vi har identifisert en del scenarier for bruk av gitpod i emner, som en bør være fortrolig med.
+
+=== Kode-eksempler
+
+Fagstaben rigger et kode-eksempel i et prosjektoppsett som lar en kompilere og kjøre (generelt bygge). Prosjektet kan kreve verktøy og rammeverk som studentene ikke (ennå) har installert på egne maskiner. Studentene åpner kodelageret i gitpod og kan umiddelbart prøve det ut, endre på det og lære av det. Dersom en vil ta vare på eksemplet, må en opprette et eget kodelager og lagre (det endrede) innholdet der vha. *git remote* og *git push*.
+
+=== Få veiledning
+
+Studenten jobber med et prosjekt i et kodelager og trenger veiledning og sender lenke til en læringsassistent, som kan åpne gitpod og jobbe i samme oppsett som studenten. Hvis læringsassistenten har rettigheter til kodelageret (f.eks. fordi det ligger i en gitlab-gruppe satt opp av fagstaben), så kan hen legge tilbake endringer evt. lage et endringsforslag.
+
+En annen mulighet er å ta et såkalt øyeblikksbilde (snapshot) som lagrer innholdet i arbeidsområdet og knytter det til en lenke. Læringsassistenten kan åpne denne lenka i gitpod og får samme innhold i sin gitpod som studenten hadde da øyeblikksbildet ble tatt. Fordelen er at en får delt innhold som det ikke naturlig å dele vha. selve kodelageret, f.eks. byggeresultater.
+
+=== Øvingsopplegg
+
+Fagstaben i et emne lager en gitlab-gruppe for emnet og semesteret, f.eks. *tdt4100/v2022* og inni denne opprettes et gitpodifisert kodelager for hver student som både fagstaben og studenten har tilgang til. Hver uke publiseres nye øvingsoppgaver (tekster, startpakke med kode og evt. tester) som kopieres inn i hvert slikt kodelager, slik at studentene kan jobbe med dem og (implisitt) levere i sitt eget emne-kodelager.
+
+=== Eksamen (!)
+
+Eksamen kan rigges omtrent som et øvingsopplegg, med et personlig kodelager pr. student, med både oppgave og (etterhvert) besvarelse i.
+
+== Gitpod og bruk av git
+
+Som nevnt klones kodelageret inn i den virtuelle maskina, og håndtering av kodelageret blir som ved kjøring på egen maskin, en bruker de vanlige *git*-kommandoene for å synkronisere med gitlab-tjeneren. En er ikke nødt til å lagre unna endringer i arbeidsområdet til tjeneren før den virtuelle maskina legges i dvale, hele arbeidsområdet arkiveres jo, men dersom en jobber med andre eller bruker VSCode i både gitpod og lokalt, så må en jo synkronisere filer via gitlab. Merk også at arkiverte arbeidsområder lagres ikke evig, de kastes etter noen uker uten bruk, så en må bruke git innimellom.
+
+Å komme i gang er i grunnen mest komplisert, fordi utgangspunktet for kodelageret kan være så forskjellig.
+
+=== Jobbe videre med andres kodelager
+
+Hvis en skal jobbe videre med et kodelager som eies av andre, så må en lage en kopi (med eller uten kobling til originalen, med kobling så kalles det gjerne en "gaffel"). En oppretter da et nytt kodelager på gitlab f.eks. på egen bruker eller under en emne-gruppe. Navigér til egen bruker eller gruppa og velge *New project* under *+*-menyen øverst.
+
+image::images/gitlab-new-project.png[width=800]
+
+Lag et tomt/blankt kodelager uten README, fordi hele innholdet skal overføres fra originalen. Hvert kodelager har sin egen adresse som brukes av git. Velg *Clone*-nedtrekksmenyen og kopier *HTTPS*-adressen (se under). Den skal brukes i en git-kommando for oppsett av git inni gitpod.
+
+image::images/gitlab-repo-url.png[width=300]
+
+For å knytte kodelageret inni gitpod til det nye kodelageret på gitlab, skriv inn `git remote set-url origin` etterfulgt av kodelager-adressen fra forrige steg. Dermed vil alle kommandoer som opererer på git-tjeneren (en såkalt _remote_)gå mot det nye kodelageret. Kommandoen `git push -u origin master` brukes først for å overføre alt git-innhold m/historikk til det nye kodelageret sin *master*-grein, og siden kan en bare bruke `git push` for å oppdatere, evt. `git pull` for å hente ned endringer fra tjeneren.
+
+Dersom en vil beholde knytningen til original-kodelageret, så endrer en først navnet
+på den opprinnelige kobling til f.eks. upstream med `git remote rename origin upstream`. Så opprettes det en ny kobling til det nye kodelageret med `git remote add origin` etterfulgt av kodelager-adressen fra forrige steg. Da vil vanlig bruk av *git push* og *git pull* gå mot det nye kodelageret, men en kan hente ned endringer fra original-kodelageret med *git fetch upstream* og innlemme dem med *git merge upstream/master* (og være beredt til å håndtere konflikter).
+
+=== Opprette nytt kodelager på gitlab
+
+Dette er i grunnen det enkleste. En bruker samme skjema som over, men velger å lage en README med det samme (om en glemmer det, så kan en lage en README på nettsiden til det nye kodelageret), og etter at kodelageret er opprettet, så åpner man bare gitpod på det nye kodelageret. Merk at selv om en kan åpne gitpod, så er ikke kodelageret automatisk gitpodifisert. Det gjør en ved å opprette *.gitpod.yml* og evt. en *docker*-fil med passende innhold, overføre disse tilbake med *git push*. For at det nye gitpod-oppsettet skal få effekt må en starte gitpod på nytt fra nettsida til kodelageret.
+
+=== Overføre lokalt kodelager til gitlab (og gitpod)
+
+Dersom du sitter med et kodelager lokalt på maskina di (som ikke finnes på gitlab), så kan det åpnes i gitpod ved å først overføre det til et kodelager på gitlab, for så å åpne det i gitpod. Prosessen blir litt som den første varianten over, en oppretter et kodelager på gitlab og angir så at det lokale kodelageret skal knyttes til det nye på gitlab (som en _remote_). Skriv inn `git remote add origin` etterfulgt av kodelager-adressen for det nye kodelageret (tilsvarende varianten over). Dette gjøres selvsagt i terminalen lokalt, evt. inni terminal-panelet i VSCode lokalt.
+
+Til slutt åpnes det nye kodelageret på gitlab i gitpod.
+
+== Gitpod-konfigurasjon med .gitpod.yml og gitpod.Dockerfile (for den dristige)
+
+Den virtuelle maskina konfigures vha. en spesiell fil med navn *.gitpod.yml* og en tilhørende *docker*-fil. Førstnevnte angir bl.a. hvilken *docker*-fil som beskriver alt som skal være ferdig installert i den virtuelle maskina. Det enkleste er å referere til en standard *docker*-fil laget for formålet f.eks. *gitpod/workspace-full-vnc*. Da får en en støtte for en rekke vanlige programmeringsspråk og kan kjøre grafiske apper på en slags virtuell skjerm som vises i gitpod eller et eget nettleser-vindu. Dersom en trenger noe ut over dette, kan en lage sin egen *docker*-fil som angir det som trengs ekstra på toppen av en standard en. Det er litt mye å dekke her, men under vises et enkelt oppsett for å bruke en nyere Java-versjon enn det som er standard i gitpod.
+
+*.gitpod.yml* (styrer oppsettet):
+
+....
+image:
+  file: .gitpod.Dockerfile
+
+tasks:
+  - init: sdk use java 16.0.1.hs-adpt
+....
+
+*.gitpod.Dockerfile* (angir innhold i virtuell maskin):
+
+....
+FROM gitpod/workspace-full-vnc
+
+USER gitpod
+
+RUN bash -c ". /home/gitpod/.sdkman/bin/sdkman-init.sh \
+             && sdk install java 16.0.1.hs-adpt \
+             && sdk default java 16.0.1.hs-adpt"
+....
+
+Det viktige her er at
+
+- *.gitpod.yml* refererer til *.gitpod.Dockerfile*
+- *.gitpod.Dockerfile* bygger på (ved å referere til) *gitpod/workspace-full-vnc*
+- *.gitpod.Dockerfile* kjører en ekstra kommando(linje) som installerer java-distribusjonen *16.0.1.hs-adpt* vha. *sdk*-programmet
+- *.gitpod.yml* kjører en kommando for å ta i bruk *16.0.1.hs-adpt* i gitpod-terminal
+
+En kan installere nær sagt hva som helst ved å skrive de riktige installasjonskommandoene inn i *.gitpod.Dockerfile* og ytterligere instruksjoner i *.gitpod.yml*. Det er litt fikkel, men en kommer langt ved å søke etter relevant *docker*-filer på https://hub.docker.com/search?q=&type=image[Dockerhub] og kopiere innhold derfra.

lectures/asciidoc/index.adoc

+:sourcedir: .
+:toclevels: 3
+
+= Forelesninger
+
+== 2021
+
+=== Introduksjon til emnet
+
+link:slides/01-course-intro.html[Lysarkene] gir en oversikt over organiseringen av emnet
+
+link:slides/02-git-plus-plus.html[Lysarkene] gir en oversikt over git, gitlab og gitpod
+
+include::{sourcedir}/gitpod.adoc[leveloffset=+2]
+
+include::{sourcedir}/ci.adoc[leveloffset=+2]
+
+=== 4. Forelesning
+
+link:slides/04-lecture.html[Lysarkene] gir en oversikt over SCRUM og Gitlab elementer som kan brukes i prosjektet.
+
+=== 5. Forelesning
+
+link:slides/05-lecture.html[Lysarkene] Q&A.
+
+=== 6. Forelesning
+
+link:slides/06-lecture.html[Lysarkene] Pair programming + more on Git.
+
+=== 7. Forelesning
+
+==== Oppsummering av øving 1
+
+link:slides/individuell-oblig.html[Lysarkene] oppsummerer den individuelle, obligatoriske øving 1
+
+==== Kodestank
+
+link:slides/kodestank.html[Lysark] om såkalt "kodestank" (code smell)
+
+
+== 8. Forelesning
+
+link:slides/08-lecture.html[Lysarkene] Unit testing.
+
+== 9. Forelesning
+
+link:slides/09-lecture.html[Lysarkene] Documentation.
+
+== 10. Forelesning
+
+link:slides/12-modular.html[Lysarkene] 2nd Group assignment + Modularization.
+link:slides/10-lecture-code-quality.html[Lysarkene] Code quality.
+
+
+
+
+== 2020
+
+=== Programvareutvikling
+
+link:slides/02-software-development.html[Lysarkene]
+
+=== Utvikling og kildekodehåndtering
+
+link:slides/03-dev-and-scm.html[Lysarkene]
+
+=== Git-demonstrasjon
+
+link:slides/04-git-demo.html[Lysarkene]
+
+=== Byggeverktøy og (litt om) testing
+
+link:slides/06-build-tools-and-some-testing.html[Lysarkene]
+
+=== Gitlab
+
+link:slides/07-gitlab.html[Lysarkene]
+
+=== Eksempel på arbeidsfly
+
+link:slides/08-workflow-example.html[Lysarkene]
+
+=== Dokumentasjon
+
+link:slides/09-documentation.html[Lysarkene]
+
+=== Enhetstesting
+
+link:slides/10-unit-testing.html[Lysarkene]
+
+=== Kodekvalitet
+
+link:slides/11-code-quality.html[Lysarkene]
+
+=== Moduler og modularitet
+
+link:slides/12-modular.html[Lysarkene]
+
+=== Designprinsipper og UML
+
+link:slides/13-solid-uml.html[Lysarkene]
+
+=== Git og gitlab
+
+link:slides/14-git-gitlab.html[Lysarkene]
+
+=== REST API
+
+link:slides/17-rest-api.html[Lysarkene]
+
+=== Generelle/felles problemer
+
+link:slides/19-common-issues.html[Lysarkene]
+
+=== Smidige verktøy
+
+link:slides/agiletools.html[Lysarkene]
+
+=== Kontinuerlig integrasjon
+
+link:slides/ci.html[Lysarkene]
+
+=== Kildekodehåndtering
+
+link:slides/scm.html[Lysarkene]

lectures/build.gradle

-plugins {
-    id 'org.asciidoctor.jvm.convert' version '3.0.0-alpha.3'
-    id 'org.asciidoctor.jvm.revealjs' version '3.0.0-alpha.3'
-}
-
-repositories {
-    jcenter()
-    maven {
-        url "https://plugins.gradle.org/m2/"
-    }
-    maven {
-    	url 'http://rubygems-proxy.torquebox.org/releases'
-    }
-}
-
-dependencies {
-    asciidoctorGems 'rubygems:asciidoctor-revealjs:2.0.0' 
-}
-
-asciidoctor {
-	sourceDir 'asciidoc'
-    sources {
-        include '*.adoc'
-    }
-    outputDir file('build/docs/asciidoc')
-	resources {
-		from('asciidoc') {
-	    	include '**/*.png'
-	 	}
-		into '.'
-	}
-    logDocuments = true
-}
-
-asciidoctorj {
-	modules {
-       // diagram.use() 
-       diagram.version '1.5.16' 
-    }
-    // useIntermediateWorkDir = true
-    attributes toc: 'left',
-    	'source-highlighter': 'highlight.js'
-
-    /*	
-	extensions {
-        block_macro (name: 'tweet') { parent, target, attributes ->
-            String content = """<div class="tweet" data-src="https://twitter.com/${target}/status/${attributes.get('1')}"></div>"""
-            config.remove 'content_model'
-            createBlock(parent, "pass", [content], [:], config)
-        }
-    }
-    */	
-}
-
-asciidoctorRevealJs {
-
-    sourceDir 'revealjs'
-    sources {
-        include '*.adoc'
-    }
-    outputDir file('build/docs/revealjs')
-	resources {
-		from('revealjs') {
-	    	include 'images/*'
-	    	include '**/*.css'
-	 	}
-		into '.'
-	}
-
-    attributes 'sourceDir': 'revealjs',
-    	'imagesDir': 'revealjs',
-        'icons':'font',
-        'iconfont-name': 'fontawesome-4.5.0'
-
-    revealjsOptions {
-        controls = true
-        slideNumber = true
-        progressBar = true
-        pushToHistory = true
-        overviewMode = true
-        touchMode = true
-        backgroundTransition = 'convex' //none , fade, slide, convex, concave, zoom
-        theme = 'sky' //'black', 'beige' , 'league', 'night', 'serif', 'simple', 'sky', 'solarized'
-    }
-
-	plugins 'rajgoel/chart/Chart.min.js'
-}
-
-revealjs {
-	version '2.0.0' // why not '3.8.0' 
-	templateGitHub {
-   		organisation = 'hakimel'
-    	repository = 'reveal.js'
-    	tag = '3.8.0'
-  	}
-}
-
-revealjsPlugins {
-    github 'rajgoel', {
-        organisation = 'rajgoel'
-        repository = 'reveal.js-plugins'
-        branch = 'master'
-    }
-}
-
-build.dependsOn 'asciidoctorRevealJs'