Merge pull request #23 from SELab-2/chore/init

README en CONTRIBUTING

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+<!-- Beschrijf wat deze pull request doet. Voeg een samenvatting van de wijzigingen en de reden voor de wijzigingen toe. -->
+
+## Context
+
+<!-- Geef extra context en uitleg waarom bepaalde keuzes zijn gemaakt in deze pull request. -->
+
+## Screenshots
+
+<!-- Voeg indien van toepassing screenshots toe om je wijzigingen uit te leggen. -->
+
+## Aanvullende opmerkingen
+
+<!-- Voeg eventuele andere informatie toe waarvan reviewers op de hoogte moeten zijn. -->
+
+<!-- Lijst eventuele gerelateerde issues. Gebruik het formaat `Fixes #<issue_number>` om het issue automatisch te sluiten wanneer de PR wordt gemerged. -->
+- Fixes #
+
+<!--
+## Richtlijnen
+
+Zorg ervoor dat het volgende in orde is voordat je de pull request indient:
+
+- De code volgt de stijlrichtlijnen van dit project.
+- Je hebt een zelfreview van de code uitgevoerd.
+- Je hebt de documentatie bijgewerkt waar nodig.
+- Alle nieuwe en bestaande unittests slagen (lokaal).
+- Je hebt de juiste labels ingesteld op deze pull request.
+-->

CONTRIBUTING.md

@@ -1,40 +1,67 @@
 # Hoe bijdragen aan Dwengo-1?
 
+Bedankt dat je wil bijdragen aan Dwengo-1!
+Hieronder vind je enkele richtlijnen om je op weg te helpen.
+
+Over het algemeen bestaat de workflow uit de volgende stappen:
+
+1. [Een issue aanmaken](#issues)
+2. [Een branch maken](#workflow)
+3. [Code schrijven](#coding-conventions)
+4. [Werk committen](#commits)
+5. [Een pull request maken](#pull-request)
+
 ## Issues
 
-Maak gebruik van de [label set](https://github.com/SELab-2/Dwengo-1/labels).
+Als je een issue aanmaakt is het belangrijk om zo veel mogelijk (relevante) informatie te geven.
+Om je op weg te helpen zijn er [templates](.github/ISSUE_TEMPLATE) voorzien.
+Gebruik deze om alle nodige informatie te verzamelen.
 
-Voor bug reports:
+Gebruik de juiste [labels](https://github.com/SELab-2/Dwengo-1/labels) om te helpen een onderscheid te maken tussen verschillende categorieën issues.
 
-Geef zo veel mogelijk informatie. Als er error berichten zijn, graag in tekst bijvoegen. Geen screenshots van error
+Ken jezelf toe aan een issue als je eraan werkt, zodat er beter een overzicht bewaard kan worden.
-messages, enkel van visuele bugs.
+Op die manier vermijd je onnodig werk.
-
-Ken jezelf toe aan een issue als je eraan werkt, zodat iedereen een overzicht heeft van waar aan gewerkt wordt en door
-wie. Zo wordt onnodig werk vermeden.
 
 ## Workflow
 
-We zullen [Gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) gebruiken
+Dit project maakt gebruik van (een minder strenge versie van) [Gitflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow).
+Dat betekent dat verschillende branches een verschillende rol hebben.
+Nieuwe branches worden aangemaakt vanuit `dev` en worden gemerged naar `dev`.
 
-Lees [hier](wiki) meer over deze beslissing
+Een overzicht:
 
-Concreet:
+- `main`: Hier worden enkel de releases gemerged. Elke merge naar `main` moet een release zijn, aangeduid met een tag (`v1.2.3`).
-
+- `dev`: Jouw branch hoort hiervan af te takken.
-- `main`
-    - Incl. tags (`v1.2.3`)
-- `dev`
     - `feat/my-feat`: Voor features die uit geen of meer dan 1 issue bestaan
     - `feat/this-#x`: Voor features die aan een issue gelinkt kunnen worden
     - `fix/something-#x`: Voor (minder dringende) bug fixes. Bug fixes worden aan een issue gelinkt.
-- `release/x.y.z`: Release prep branch
+- `release/x.y.z`: Voorbereidingen voor een release. Hier worden enkel bug fixes en hotfixes gemerged.
+
+Lees [hier](https://github.com/SELab-2/Dwengo-1/wiki/Developmentstrategie-keuzes#gitflow) meer over de beslissing om Gitflow te gebruiken.
+
+We hebben ervoor gekozen om `main` en `dev` te beschermen.
+Zie ook [pull request](#pull-request).
+
+## Coding conventions
+
+Om de code consistent te houden, maken dit project gebruik van enkele tools:
+
+- Formatting: [Prettier](https://prettier.io/), zorgt ervoor dat de code consistent geformatteerd is.
+- Linting: [ESLint](https://typescript-eslint.io/), zorgt er o.a. voor dat de code geen "slechte" constructies bevat.
+
+Je kan ze handmatig uitvoeren met `npm run lint` en `npm run format`.
+
+Deze tools worden niet standaard automatisch uitgevoerd bij een commit.
+Automatisch uitvoeren bij een commit kan met [git hooks](https://git-scm.com/docs/githooks).
 
 ## Commits
 
-Maken gebruik van [conventional commits](https://www.conventionalcommits.org/)
+**Conventionele commits**
 
-Lees [hier](wiki) meer over deze beslissing
+Dit project maakt gebruik van [conventional commits](https://www.conventionalcommits.org/).
 
-Concreet:
+Dit betekent dat elke commit een duidelijke boodschap moet hebben, die volgens een bepaald formaat is opgesteld.
+In het kort ziet dat er zo uit:
 
 ```
 <type>(<optional scope>): <description>
@@ -43,29 +70,36 @@ type options:
     feat, fix, refactor, test, docs, build, ci, chore, ...
 ```
 
-Als je een commit 'fixt', gebruik dan [
+Lees [hier](https://github.com/SELab-2/Dwengo-1/wiki/Developmentstrategie-keuzes#conventionele-commits) meer over de beslissing om conventionele commits te gebruiken.
-`git commit --fixup`](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordltcommitgt)
 
-Als je een commit niet alleen hebt geschreven, maak dan
+**Andere tips**
-een [commit met meerdere auteurs](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors).
 
-## Pull request...
+Als je een commit 'fixt', gebruik dan [`git commit --fixup`](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordltcommitgt)
 
-Als je aan visuele features werkt, voeg dan een screenshot van de omgeving van de feature toe, voor en nadat de feature
+Als je een commit niet alleen hebt geschreven, maak dan een [commit met meerdere auteurs](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors).
-geïmplementeerd werd.
 
-Start een draft pull request vanaf je een nieuwe feature branch pusht naar de server.
+## Pull request
 
-Policies
+Eens je code hebt geschreven en gecommit, is het tijd om een pull request te maken.
+Het is fijn als je meteen ([draft](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests)) pull requests maakt, zodat anderen kunnen meekijken en feedback kunnen geven.
 
-- naar `main`: kan enkel vanuit `release/x.y.z`
+Om je op weg te helpen is er een [template](.github/PULL_REQUEST_TEMPLATE.md) voorzien.
-- naar `dev`: wordt nagekeken alvorens te mergen
+Door deze in te vullen, zorg je ervoor dat de reviewer een duidelijk beeld heeft van wat je hebt gedaan.
-- elders: vrije keuze
 
-## Coding conventions
+Als je aan visuele features werkt, voeg dan een screenshot van de omgeving van de feature toe, voor en na dat de feature geïmplementeerd werd.
 
-- Formatting: [Prettier](https://prettier.io/)
+**Branch protection**
-- Linting: Maak gebruik van [ESLint](https://typescript-eslint.io/) of aan de hand van de [
-  `npm` commando's](package.json).
 
-Voel je vrij om zelf commit hooks te installeren, maar we dwingen dit niet af.
+Je zult merken dat sommige branches [beschermd](https://docs.github.com/en/github/administering-a-repository/about-protected-branches) zijn.
+Dit betekent dat je niet zomaar kan mergen naar deze branches:
+
+- `main`: kan enkel vanuit `release/x.y.z`
+- `dev`: wordt nagekeken alvorens te mergen
+
+Elders kan je vrij mergen.
+
+Het zou kunnen dat je code bepaalde checks moet doorstaan alvorens te mergen.
+Dit kan gaan van een simpele lint check tot een volledige test suite die moet slagen.
+Tag gerust een maintainer als je denkt dat je code klaar is om gemerged te worden.
+
+## Dankjewel!

README.md

@@ -5,15 +5,15 @@
 OneDrive</a></span>
 <span><a href="https://www.figma.com/files/project/339220191" alt="Figma sjabloon">
 Figma</a></span>
-<span><a href="../Dwengo-opgave" alt="projectopgave">
+<span><a href="https://github.com/SELab-2/Dwengo-opgave" alt="projectopgave">
 Projectopgave</a></span>
 </p>
 
 <ul align="center" style="list-style-type: none">
-<li>Projectleider: Fransisco Van Langenhove (@Gabriellvl)</li>
+<li>Projectleider: Fransisco Van Langenhove (<a href="https://github.com/Gabriellvl">@Gabriellvl</a>)</li>
-<li>Technische lead: Tibo De Peuter (@tdpeuter)</li>
+<li>Technische lead: Tibo De Peuter (<a href="https://github.com/tdpeuter">@tdpeuter</a>)</li>
-<li>Systeembeheerder: Timo De Meyst (@kloep1)</li>
+<li>Systeembeheerder: Timo De Meyst (<a href="https://github.com/kloep1">@kloep1</a>)</li>
-<li>Customer relations officer: Adriaan Jacquet (@WhisperinCheetah)</li>
+<li>Customer relations officer: Adriaan Jacquet (<a href="https://github.com/WhisperinCheetah">@WhisperinCheetah</a>)</li>
 </ul>
 
 Dit is de monorepo voor [Dwengo-1](https://sel2-1.ugent.be), een interactief leerplatform waar leerkrachten opdrachten
@@ -23,28 +23,31 @@ en lessen kunnen samenstellen hun leerlingen en hun vooruitgang kunnen opvolgen.
 
 ### Quick start
 
-1. Installeer Docker en Docker Compose op je systeem (zie [Docker](https://docs.docker.com/get-docker/)).
+1. Installeer Docker en Docker Compose op je systeem (zie [Docker](https://docs.docker.com/get-docker/) en [Docker Compose](https://docs.docker.com/compose/)).
-2. Clone de repository.
+2. Clone deze repository.
-3. Voer `docker-compose up` uit in de root van de repository.
+3. Voer `docker compose up` uit in de root van de repository.
 
 ```bash
 docker compose version
 git clone https://github.com/SELab-2/Dwengo-1.git
 cd Dwengo-1
-docker-compose up
+docker compose up
 ```
 
 ### Handmatige installatie
 
-Zie de submappen voor de installatie-instructies van de verschillende services.
+Zie de submappen voor de installatie-instructies van de [frontend](./frontend/README.md) en [backend](./backend/README.md).
 
 ## Architectuur
 
-```
+![Architectuur](./docs/architecture/schema.png)
-hier overzichtsdiagram invoegen
-```
 
-We maken gebruik van ... Meer informatie over deze ontwerpsbeslissingen kan je vinden in de [architectuurdocumentatie](./architectuur).
+De tech-stack bestaat uit:
+
+- **Frontend**: TypeScript + Vue.js + Vuetify
+- **Backend**: TypeScript + Node.js + Express.js + TypeORM + PostgreSQL
+
+Voor meer informatie over de keuze van deze tech-stack, zie [designkeuzes](https://github.com/SELab-2/Dwengo-1/wiki/Design-keuzes).
 
 ## Bijdragen aan Dwengo-1
 

backend/README.md

@@ -0,0 +1,22 @@
+# dwengo-1-backend
+
+## Project setup
+
+```shell
+npm install
+```
+
+Setup the environment variables in a `.env` file in the root of the project. You can use the `.env.example` file as a template.
+
+### Development
+
+```shell
+npm run dev
+```
+
+### Production
+
+```shell
+npm run build
+npm run start
+```

docs/architecture/schema.py

@@ -0,0 +1,30 @@
+from diagrams import Cluster, Diagram
+from diagrams.custom import Custom
+from diagrams.onprem.certificates import LetsEncrypt
+from diagrams.onprem.container import Docker
+from diagrams.onprem.database import PostgreSQL
+from diagrams.onprem.logging import Loki
+from diagrams.onprem.monitoring import Grafana
+from diagrams.onprem.network import Nginx
+from diagrams.programming.framework import Vue
+from diagrams.programming.language import Nodejs
+from diagrams.programming.flowchart import InputOutput
+
+with Diagram("Dwengo-1 architectuur", filename="docs/architecture/schema", show=False):
+    reverse_proxy = Nginx("reverse proxy")
+    reverse_proxy >> LetsEncrypt("SSL")
+
+    with Cluster("Docker"):
+        Docker()
+
+        frontend = Vue("/")
+        backend = Nodejs("/api")
+        reverse_proxy >> frontend
+        frontend >> backend >> InputOutput("MikroORM") >> PostgreSQL()
+
+        backend >> Loki("logging") >> Grafana("monitoring")
+
+    with Cluster("Dwengo"):
+        dwengo = Custom("Dwengo", "../../assets/img/dwengo-groen-zwart.png")
+
+    backend >> dwengo

docs/requirements.txt

@@ -0,0 +1 @@
+diagrams==0.24.1

frontend/README.md

@@ -6,6 +6,8 @@ This template should help get you started developing with Vue 3 in Vite.
 
 [VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur).
 
+Webstorm should work out of the box.
+
 ## Type Support for `.vue` Imports in TS
 
 TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types.

package.json

@@ -8,6 +8,7 @@
         "build": "npm run build --ws",
         "format": "npm run format --ws",
         "format-check": "npm run format-check --ws",
+        "generate-docs": "python3 -m venv .venv && source .venv/bin/activate && pip install -r docs/requirements.txt && python docs/architecture/schema.py",
         "lint": "npm run lint --ws",
         "test:unit": "npm run test:unit --ws"
     },