Merge pull request #9 from hpi-schul-cloud/BC-5532-move-docu

BC-5532 - Move FE docu to new repo

docs/nuxt-client/0_GettingStarted.md

@@ -0,0 +1,55 @@
+---
+sidebar_position: 1
+---
+
+# Getting Started
+
+## Development Setup
+
+> **Note:** Please **_don't use yarn_** !!! We decided to use npm across all of our repositories.
+
+In order to run this client, you need to have the [legacy-client](https://github.com/hpi-schul-cloud/schulcloud-client) and [schulcloud-server](https://github.com/hpi-schul-cloud/schulcloud-server) set up and running. See for documentation on how to do that in the respective repositories.
+
+### Start the Server
+
+0. Clone the repository
+
+    ```sh
+    git clone [email protected]:hpi-schul-cloud/nuxt-client.git
+    ```
+
+1. Install the required dependencies:
+
+   ```sh
+   npm ci
+   ```
+
+2. Start the development server:
+
+   ```sh
+   npm run serve
+   ```
+
+   By default the server will listen on the URL [http://localhost:4000](http://localhost:4000)
+
+### Unit Tests
+
+```bash
+# Run all (unit) tests
+npm run test
+```
+
+### Lint
+
+```bash
+npm run lint
+```
+
+## Editor Setup
+
+We are using Visual Studio Code as our default deveopment-IDE. In /.vscode you can find two templates to setup your IDE:
+
+- `launch.default.json` (copy its content and us it in `launch.json`)
+- `settings.default.json` (copy its content and us it in `settings.json`)
+
+For a list of recommended Visual Studio Code extensions please refer to `extensions.json`.

docs/nuxt-client/1_CodeConventions.md

@@ -0,0 +1,70 @@
+---
+sidebar_position: 2
+---
+
+# Code Conventions
+
+<!-- vscode-markdown-toc -->
+- [Code Conventions](#code-conventions)
+  - [filenames](#filenames)
+  - [data-testid(s)](#data-testids)
+  - [ts-ignore comments](#ts-ignore-comments)
+  - [Composables](#composables)
+
+<!-- vscode-markdown-toc-config
+	numbering=false
+	autoSave=true
+	/vscode-markdown-toc-config -->
+<!-- /vscode-markdown-toc -->
+
+## filenames
+
+Files should be consistently named like this:
+| file content |                      filename |
+| ------------ | ----------------------------: |
+| Components   |           `YourComponent.vue` |
+| Pages        |       `YourPageName.page.vue` |
+| Layouts      |   `yourLayoutName.layout.vue` |
+| Composables  | `yourComponent.composable.ts` |
+| Tests        |        `yourTestFile.unit.ts` |
+| Utils        |                 `yourUtil.ts` |
+| Pinia stores |             `yourFilename.ts` |
+| Vuex stores  |            `your-filename.ts` |
+
+**Near future**: The structure of this project will move from the old *Atomic Design* (= using molecules- and atoms- folders) to a more use-case-centeric approach.
+Details are documented here: [Vue 3 project structure](https://docs.dbildungscloud.de/x/oYAgDQ)
+
+**Far future**: Linter Rules to enforce the project structure as decided in Frontend Arc Group Meeting 2022-08-26.
+
+**Current status**: For the moment we started to break up the *Atomic Design* by introducing feature-centric folders. (e.g. ``src / components /share-course / ...``).
+
+## data-testids
+
+Please use ``<div ... data-testid="some-example" ...>`` in your HTML-code if you want to define a data-testid.
+
+- do not use uppercase-characters
+- only use one dash - right after data
+
+We also recommend to use **ref**s instead of data-testids. But if you do that, you need to be careful when removing them... as they could be used in the component-code AND in tests:
+
+- [VueJs - template refs](https://vuejs.org/guide/essentials/template-refs.html)
+- [VueTestUtils - ref](https://v1.test-utils.vuejs.org/api/#ref)
+
+Also look here: *Frontend Arc Group: Meeting Notes 2022-11-04*
+
+## ts-ignore-comments
+
+Everybody should try to avoid ``// @ts-ignore`` and try his/her best to define the types of variables in TypeScript files.
+
+Also look here: *Frontend Arc Group: Meeting Notes 2022-10-28*
+
+## composables
+
+Composables are a great way to make our code more reusable and to extract code from components. If you want to write a composable, consider using one of these well documented and well tested ones:
+[VueUse - Collection of Vue Composition Utilities](https://vueuse.org/)
+
+If you write a composable:
+
+- it should have the extension ``.composable.ts``
+- should be placed in your feature folder (see section "directory structure" above), if it is only used inside of your feature
+- should be placed in the global folder ``/ src / composables``, if it is used in multiple features

docs/nuxt-client/2_ProjectStructure.md

@@ -0,0 +1,162 @@
+---
+sidebar_position: 3
+---
+
+# Project Structure
+
+## Description of the Structure
+
+The projects code is separated into building blocks.
+
+## What is a building-block?
+
+A **building-block** is a "container" were we place most of our applications logic and components. Each building-block is defined by an `index.ts (Barrel-File)` describing it's exported content (public API of a building-block) and a `type`.
+
+Utilizing linting rules and the index.ts we can ensure that each building-block only exposes files which are meant to be used application-wide. This way we achieve a strong separation of concern across the whole application.
+
+Our linting rule is based on the following concept:
+
+[Enforce Project Boundaries | Nx](https://nx.dev/core-features/enforce-project-boundaries)
+
+`Note: in above documentation **libraries** are equivalent to building-blocks and **tags** represent the types defined below.`
+
+## Types of building-blocks
+
+**Page**
+
+Contains a subpage of the application. Orchestrates Feature and UI building-blocks.
+
+`Example: page-dashboard`
+
+**Feature**
+
+Complex features with **stateful / smart components**. Usually specialized to fulfill specific roles in the App. Can also contain presentational components that are specialized for this feature.
+
+`Example: feature-calendar`
+
+**UI**
+
+**Stateless / presentational components** which get their data via props and emit events. Usually less specialized.
+
+`Example: ui-forms`
+
+**Data**
+
+State and API-access. Does not contain any visual components. They are the data-sources of all smart components.
+
+`Example: data-auth`
+
+**Util**
+
+Contains shared low-level code.
+
+`Example: util-form-validators`
+
+## Type: Page
+
+### What is it?
+
+A page building-block represents a **subpage** of the application. It contains the layout component and orchestrates feature and ui building blocks to create a subpage. It can not be imported into any other type of building-block. It is **only imported by the vue-router** and should be **lazy-loaded** if possible.
+
+### Naming Convention
+
+Placed in folder **page**
+
+### Can import types
+
+data, util, ui, feature
+
+## Type: Feature
+
+### What is it?
+
+A feature building-block contains a set of files that represent a business use case in an application.
+
+Most of the components of features are **stateful / smart components** that interact with data sources. This type also contains most of the UI logic, form validation code, etc.
+
+### Naming Convention
+
+Placed in folder **feature**
+
+### Can import types
+
+data, util, ui, feature
+
+## Type: UI
+
+### What is it?
+
+A ui building-block mainly contains **Stateless / presentational components** which are used all across the application. They don't have access to stores and do not use features in their templates. All data needed for components in ui building-blocks comes from props.
+
+### Naming Convention
+
+Placed in folder **ui**
+
+### Can import types
+
+util, other ui
+
+## Type: Data
+
+### What is it?
+
+A data building-block contains **stores and api-services**. It does not contain any view components. They serve as data-sources for feature and page building blocks.
+
+### Naming Convention
+
+Placed in folder **data**
+
+### Can import types
+
+util, other data
+
+## Type: Util
+
+### What is it?
+
+A utility building-block contains **low level code** used by many building-blocks. Often there is no framework-specific code and the building-block is simply a collection of types, utilities, pure functions, factories or composables.
+
+### Naming Convention
+
+Placed in folder **util**
+
+### Can import types
+
+other util
+
+# How to pick the correct type for my Task
+
+`To render this graph in VS-Code markdown preview install this extension: bierner.markdown-mermaid`
+
+```mermaid
+flowchart TD
+    A[Your Task] --> B[Imagine the different requirements of the Task]
+    B --> C{Do I need a new subpage}
+    C -->|Yes| D(type: page)
+    C -->|No| E{Do I need UI?}
+    E --> |No| F{Do I need State?}
+    E --> |Yes| G{Do I need State?}
+    F -->|Yes| H(type: data)
+    F -->|No| I(type: util)
+    G -->|Yes| J(type: feature)
+    G -->|No| K(type: ui)
+    H --> L[Are all requirements of your task placed in a building-block?]
+    I --> L
+    J --> L
+    K --> L
+    D --> L
+    L -->|Yes| M[Happy Coding!]
+    L -->|No| O[You need an additional building-block]
+    O --> B
+    M -.-> P[Evaluate your choices as a part of your review and refactor when neccessary]
+```
+
+# Matrix of allowed imports
+
+| Allowed to Import &#8594; <br/> It is &#8595;  | page | feature | data | ui  | util |
+| ---------------------------------------------- | ---- | ------- | ---- | --- | ---- |
+| page                                           |      | ✔       | ✔    | ✔   | ✔    |
+| feature                                        |      | ✔       | ✔    | ✔   | ✔    |
+| data                                           |      |         | ✔    |     | ✔    |
+| ui                                             |      |         |      | ✔   | ✔    |
+| util                                           |      |         |      |     | ✔    |

docs/nuxt-client/3_GitConventions.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 4
+---
+
+# Git Conventions
+
+Each change should be done in a Ticket (no matter how small).
+
+We use a [Feature Branch model](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow). Start a branch from main and make a PR to main.
+
+**Branch naming:**
+
+`{{ PROJECT_ABBREVIATION }}-{{ NUMBER }}-word1-word2-word2`
+
+e.g.: ``BC-1234-course-copy``
+
+We try to keep branch names small. The Ticket Number should be in Uppercase (e.g BC-1234) but the namespace should be in lowercase. It should stay below 64 letters.
+
+## Pull Requests
+
+Pull Requests must contain a relevant description (template provides useful information, when creating the PR).
+
+In case of UI changes also put a screenshot and talk to UX if thats fine like it is.
+All Pull Requests Criterias (as defined in deployment pipeline) must be green before merge,
+e.g. 1 approving review, unit tests or QA checkbox in PR template.
+
+We merge by squash strategy. The squashed commit subject should start with a ticket number and end with a PR number. Write commit messages in imperative and active.
+
+**Example:**
+
+```Text
+BC-1993 - lesson lernstore and geogebra copy (#3532)
+
+In order to make sure developers in the future can find out why changes have been made,
+we would like some descriptive text here that explains what we did and why.
+
+- change some important things
+- change some other things
+- refactor some existing things
+
+# We dont need to mention tests, changes that didnt make it to main, linter, or other fixups
+# only leave lines that are relevant changes compared to main
+# comments like this will not actually show up in the git history
+```
+
+**Note for working with Windows:** We strongly recommend to let git translate line endings. Please set `git config --global --add core.autocrlf` input when working with windows.