diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..e9fb04c6 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,28 @@ + + +## Context + + + +## Screenshots + + + +## Aanvullende opmerkingen + + + + +- Fixes # + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 83d1f83b..4890521b 100755 --- a/CONTRIBUTING.md +++ b/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 -messages, enkel van visuele bugs. - -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. +Ken jezelf toe aan een issue als je eraan werkt, zodat er beter een overzicht bewaard kan worden. +Op die manier vermijd je onnodig werk. ## 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` - - Incl. tags (`v1.2.3`) -- `dev` +- `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. - `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: ``` (): @@ -43,29 +70,36 @@ type options: feat, fix, refactor, test, docs, build, ci, chore, ... ``` -Als je een commit 'fixt', gebruik dan [ -`git commit --fixup`](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordltcommitgt) +Lees [hier](https://github.com/SELab-2/Dwengo-1/wiki/Developmentstrategie-keuzes#conventionele-commits) meer over de beslissing om conventionele commits te gebruiken. -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). +**Andere tips** -## 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 -geïmplementeerd werd. +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). -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` -- naar `dev`: wordt nagekeken alvorens te mergen -- elders: vrije keuze +Om je op weg te helpen is er een [template](.github/PULL_REQUEST_TEMPLATE.md) voorzien. +Door deze in te vullen, zorg je ervoor dat de reviewer een duidelijk beeld heeft van wat je hebt gedaan. -## 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/) -- Linting: Maak gebruik van [ESLint](https://typescript-eslint.io/) of aan de hand van de [ - `npm` commando's](package.json). +**Branch protection** -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! diff --git a/README.md b/README.md index 8dc37472..db5b63a4 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,15 @@ OneDrive Figma - + Projectopgave

    -
  • Projectleider: Fransisco Van Langenhove (@Gabriellvl)
    • -
  • Technische lead: Tibo De Peuter (@tdpeuter)
    • -
  • Systeembeheerder: Timo De Meyst (@kloep1)
    • -
  • Customer relations officer: Adriaan Jacquet (@WhisperinCheetah)
    • +
  • Projectleider: Fransisco Van Langenhove (@Gabriellvl)
    • +
  • Technische lead: Tibo De Peuter (@tdpeuter)
    • +
  • Systeembeheerder: Timo De Meyst (@kloep1)
    • +
  • Customer relations officer: Adriaan Jacquet (@WhisperinCheetah)
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/)). -2. Clone de repository. -3. Voer `docker-compose up` uit in de root van de repository. +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 deze 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 -``` -hier overzichtsdiagram invoegen -``` +![Architectuur](./docs/architecture/schema.png) -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 diff --git a/assets/img/dwengo-groen-zwart.png b/assets/img/dwengo-groen-zwart.png new file mode 100644 index 00000000..9d83c92f Binary files /dev/null and b/assets/img/dwengo-groen-zwart.png differ diff --git a/assets/img/dwengo-groen-zwart.svg b/assets/img/dwengo-groen-zwart.svg new file mode 100644 index 00000000..0da7a37d --- /dev/null +++ b/assets/img/dwengo-groen-zwart.svg @@ -0,0 +1,61 @@ + +image/svg+xml diff --git a/backend/README.md b/backend/README.md new file mode 100644 index 00000000..76bc8eae --- /dev/null +++ b/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 +``` diff --git a/docs/architecture/schema.png b/docs/architecture/schema.png new file mode 100644 index 00000000..616d896c Binary files /dev/null and b/docs/architecture/schema.png differ diff --git a/docs/architecture/schema.py b/docs/architecture/schema.py new file mode 100644 index 00000000..87a59f9a --- /dev/null +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..76c7036b --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +diagrams==0.24.1 diff --git a/frontend/README.md b/frontend/README.md index 6714b3a7..f798f404 100644 --- a/frontend/README.md +++ b/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. diff --git a/package.json b/package.json index 59a2e01d..db7f5ba3 100644 --- a/package.json +++ b/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" },