From f92b55096fcfc7ec7ce9954fcb6de14326f9f6fb Mon Sep 17 00:00:00 2001 From: Moritz Zeumer Date: Fri, 16 Feb 2024 13:39:02 +0100 Subject: [PATCH] :tada: update frontent readme and split into two files --- frontend/README.md | 286 ++++--------------- frontend/docs/Technologies-and-Guidelines.md | 242 ++++++++++++++++ 2 files changed, 301 insertions(+), 227 deletions(-) create mode 100644 frontend/docs/Technologies-and-Guidelines.md diff --git a/frontend/README.md b/frontend/README.md index e763a302..75aeeb57 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,314 +1,146 @@ # ESID - Frontend Developer Documentation + ## Table of Contents - - [Getting Started](#getting-started) - - [Prerequisites](#prerequisites) - - [Initializing](#initializing) + - [Forking and Cloning](#forking-and-cloning) + - [Initializing ESID](#initializing-esid) - [Development](#development) - [Running Tests](#running-tests) - [Generating Coverage Reports](#generating-coverage-reports) - [Formatting Code](#formatting-code) - - [Linting](#linting) + - [Linting Code](#linting-code) - [Building Releases](#building-releases) -- [Technologies](#technologies) -- [Guidelines](#guidelines) - - [TypeScript](#typescript) - - [React](#react) - - [Redux](#redux) - - [Design and Layout](#design-and-layout) - - [Testing](#testing) - - [Performance](#performance) - - [Documentation](#documentation) - - [Internationalization](#internationalization) - - [Accessibility](#accessibility) - - [Code Style](#code-style) - - [Imports](#imports) + - [Committing, Pushing, and Pull Request](#committing-pushing-and-pull-request) ## Getting Started -### Prerequisites +> [!IMPORTANT] +> To work with the frontend you need to download and install _Node.js_, and the _Node Package Manager_ (npm). You can download the latest release from their website: [NodeJS.org](https://nodejs.org/en/) + +> [!TIP] +> Our used Technologies and Guidelines can be found [here](docs/Technologies-and-Guidelines.md). + -To work with the frontend you need to download and install _Node.js_, and the _Node Package Manager_ (npm). You can -download the latest release from their website: https://nodejs.org/en/ +### Forking and Cloning -### Initializing +Start by forking the repository by clicking the **Fork** button on the top right of this page. +This creates a copy of this repository under your account. + +Next, clone the forked repository: +```bash +git clone git@github.com:/ESID.git +cd ESID +git remote add upstream git@github.com:DLR-SC/ESID.git +git checkout develop +``` -After checking out the repository go to the `frontend` folder and use npm to download the dependencies: +> [!NOTE] +> The `develop` branch contains our latest developed features as outlined in our [Branching Strategy](#branching-strategy). +In compliance with this strategy you can create your own branch for your changes: ```bash -git clone https://github.com/DLR-SC/ESID.git -cd ESID/frontend +git checkout -b feature/my-feature +# or +git checkout -b fix/my-bugfix +``` +On this branch you can perform your changes, push to a feature branch and create a pull request to ESID's develop branch. + + +### Initializing ESID + +After checking out a branch go to the `frontend` folder and use npm to download and install the dependencies: +```bash +cd frontend # assuming you are in the root repository folder () npm install ``` + ### Development You can set up and start a development server with the command: - ```bash npm run start ``` - This will host a server on http://localhost:8080/, where the website will be displayed. After running the command, your default browser should automatically open with the specified address (Internet Explorer is not supported). Changes to your code will automatically be compiled, and the website will refresh itself. + ### Running Tests To run tests you can simply use: - ```bash npm run test ``` - This will run all tests in the `src/__tests__` folder. The results will be printed to the console, and a JUnit report will be generated into `reports/jest-junit.xml`. If you want to run a specific test only, you can run: - ```bash npm run test -- -t='deepCopy' # Runs all deep copy tests. npm run test -- -t='deepCopy array' # Runs only the deep copy array test. ``` + ### Generating Coverage Reports To create a coverage report run: - ```bash npm run coverage ``` - The results will be printed to console, and to a clover file in `reports/clover.xml`. + ### Formatting Code To automatically format all code in accordance to our guideline you can run: - ```bash npm run format ``` +> [!TIP] +> You should run this and the [linter](#linting-code) before making a commit or pull request. -You should run this before committing. -### Linting +### Linting Code To automatically test code against a subset of our coding conventions you can run: - ```bash npm run lint ``` +> [!TIP] +> You should run this and the [formatter](#formatting-code) before making a commit or pull request. -You should run this before committing. ### Building Releases Release build can be created with the simple command: - ```bash npm run build ``` - The resulting release will be in the `dist` folder. If you want to test a release build you can run: - ```bash npm run preview # or npm run build-and-preview ``` -## Technologies - -The project makes use of some core technologies and libraries. You should always prefer their features over other -libraries. Also try to learn and keep up with their best practices and guidelines. - -- **TypeScript**: Type safety and increasing productivity. -- **React**: Efficient and robust user interface management. -- **Redux**: Efficient and robust state management. -- **Material UI**: Good looking user interface design and responsive layout. - -## Guidelines - -In general developers should follow the best practices of the libraries they use. - -### TypeScript - -- Try to write all code in TypeScript. Only resort to JavaScript if it is absolutely necessary. -- Avoid the use `any`. If there is no type information available, create an interface that describes the type. - -### React - -- Make small individual components that fulfill as small of a role as possible. -- Strongly prefer React-Hooks over class components. - -### Redux - -Application state management is done using [Redux](https://redux.js.org/). We use the -[Redux Toolkit](https://redux-toolkit.js.org/) to easier work with the framework. -[React Redux](https://react-redux.js.org/) provides the interface between React and Redux. - -While it is possible to manage all state with Redux, it should be preferred to use React's `props` functionality to -manage local component state. Redux should only be used, when the state affects large portions of the application that -would be difficult to handle with React's `props` alone. - -### Design and Layout - -- The frontend should follow the [Material Design guidelines](https://material.io/). - - The [Material UI](https://material-ui.com/) library does conform to these guidelines. So make use of it as much as - possible. - - For icons make use of [Material Icons](https://fonts.google.com/icons). -- The application should always look best in a 16:9 ratio with 1920x1080 and 2560x1440 pixel resolutions. -- The layout should be as responsive as possible, but the previous point has priority. -- The UI should be self describing. To ensure that all functionality can be understood add tooltips to components. -- The frontend uses a global theme based on the following guidelines: -
- Design Guidelines for Colors and Typography (-- Click to expand --) - - ![](docs/images/ThemeGuidelines.svg 'ESID Design Guidelines') - - **The alternative text color for lighter and darker variants where the contrast is not high enough is always either `#F2F2F2` (light text), or `#0C0B0D` (dark text).** - - - The Spacing is done in 5 steps: `0 px`, `4 px`, `8 px`, `12 px`, and `26 px` - -
- - - The theme is provided using the [MUI Theme Provider](https://mui.com/customization/theming 'mui.com') - -
- It can be accessed in components like this: (-- Click to expand --) - - ```tsx - import {useTheme} from '@mui/material/styles'; - - export default function MyComponent(): JSX.Element { - const theme = useTheme(); - - return ( - - - ); - ``` - -
- -### Testing - -All code should be tested: - -- Pure TypeScript should be tested using unit tests with a 100% coverage. -- UI code should be tested using the react-testing-library. - -### Performance - -New code should be checked for Performance degradation. -Use the Browser Based Profiling Tools (Chrome/Firefox): - -- [React Developer Tools](https://beta.reactjs.org/learn/react-developer-tools) (Profiler) -- Performance insights (Chrome) -- Lighthouse (Chrome) - -### Documentation - -Code should be documented as much as possible. Each class and function should contain a detailed description of what it -does, what inputs it gets and what outputs it produces. Document only functions that require it. Getters and setters for -example don't to be documented unless they do something unconventional. - -### Internationalization - -All text in the application should be internationalized with at least German and English support. To internationalize -texts the [react-i18next](https://react.i18next.com/) framework is used. - -You can add translations in the `locales/-.json5` files. The following code snippets show -how to use a translation in a React-Hook. - -`locales/en-global.json5`: - -```json -{ - "helloWorld": "Hello, World!" -} -``` - -`locales/de-global.json5`: - -```json -{ - "helloWorld": "Hallo, Welt!" -} -``` +### Committing, Pushing, and Pull Request -`HelloWorld.tsx`: +> [!NOTE] +> When you want to commit changes please keep our [guideline for commit messages](docs/Technologies-and-Guidelines.md#commit-messages) in mind to have a meaningful commit history. -```tsx -import React from 'react'; -import {useTranslation} from 'react-i18next'; - -export default function HelloWorld(): JSX.Element { - const {t} = useTranslation(); - return

{t('helloWorld')}

; -} +Once you are done with your changes make sure you have pushed them to your forked repository with: +```bash +git push origin your-branch-name # i.e. feature/my-feature or fix/my-bugfix ``` - -### Accessibility - -The application should conform to modern accessibility (a11y) guidelines. We use -[Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/) to check for a11y problems. During a pull request -a Lighthouse report is automatically generated during the CI checks. - -### Code Style - -Function names, parameters, variables and class members should be written in `camelCase`. The exception for functions -are React-Hooks, which should be written in `PascalCase`. In addition, classes and interfaces should also be written in -`PascalCase`: - -```tsx -function myFunction(myParameter: string) { - const myVariable = myParameter; -} - -function MyHook() { - return
Hello World
; -} - -interface MyInterface { - myMember: string; -} - -class MyClass { - myMember: MyInterface; -} +When there were changes to ESID's `develop` branch in the meantime, you will need to merge those to your fork before creating a pull request: +``` bash +git fetch upstream +git merge upstream/develop ``` -Try to use `const` as much as possible and use `let` otherwise. Never use `var`! +Once everything is merged and conflicts are resolved can create a pull request on GitHub to ESID's develop branch. :tada: +> [!TIP] +> Make sure to add a goo description of your changes and go over the checklist in the pull request template to make it easier for the reviewer to go through your changes and give helpful feedback and suggestions. -### Imports - -To optimize the final size of the bundle it is important to make imports as granular as possible to allow for the best -dead code removal. This is especially important for the material icons package. - -Example: - -```tsx -// DON'T DO THIS, it will import ALL the material icons into our application: -import {LockIcon} from '@mui/icons-material'; - -// Instead do this, to insure only the used icons are being imported: -import LockIcon from '@mui/icons-material/Lock'; -``` diff --git a/frontend/docs/Technologies-and-Guidelines.md b/frontend/docs/Technologies-and-Guidelines.md new file mode 100644 index 00000000..edd0df6c --- /dev/null +++ b/frontend/docs/Technologies-and-Guidelines.md @@ -0,0 +1,242 @@ +## Technologies + +The project makes use of some core technologies and libraries. You should always prefer their features over other +libraries. Also try to learn and keep up with their best practices and guidelines. + +- **TypeScript**: Type safety and increasing productivity. +- **React**: Efficient and robust user interface management. +- **Redux**: Efficient and robust state management. +- **Material UI**: Good looking user interface design and responsive layout. + +## Guidelines + +In general developers should follow the best practices of the libraries they use. + +### TypeScript + +- Try to write all code in TypeScript. Only resort to JavaScript if it is absolutely necessary. +- Avoid the use `any`. If there is no type information available, create an interface that describes the type. + +### React + +- Make small individual components that fulfill as small of a role as possible. +- Strongly prefer React-Hooks over class components. + +### Redux + +Application state management is done using [Redux](https://redux.js.org/). We use the +[Redux Toolkit](https://redux-toolkit.js.org/) to easier work with the framework. +[React Redux](https://react-redux.js.org/) provides the interface between React and Redux. + +While it is possible to manage all state with Redux, it should be preferred to use React's `props` functionality to +manage local component state. Redux should only be used, when the state affects large portions of the application that +would be difficult to handle with React's `props` alone. + +### Design and Layout + +- The frontend should follow the [Material Design guidelines](https://material.io/). + - The [Material UI](https://material-ui.com/) library does conform to these guidelines. So make use of it as much as + possible. + - For icons make use of [Material Icons](https://fonts.google.com/icons). +- The application should always look best in a 16:9 ratio with 1920x1080 and 2560x1440 pixel resolutions. +- The layout should be as responsive as possible, but the previous point has priority. +- The UI should be self describing. To ensure that all functionality can be understood add tooltips to components. +- The frontend uses a global theme based on the following guidelines: +
+ Design Guidelines for Colors and Typography (-- Click to expand --) + + ![](docs/images/ThemeGuidelines.svg 'ESID Design Guidelines') + + **The alternative text color for lighter and darker variants where the contrast is not high enough is always either `#F2F2F2` (light text), or `#0C0B0D` (dark text).** + + - The Spacing is done in 5 steps: `0 px`, `4 px`, `8 px`, `12 px`, and `26 px` + +
+ + - The theme is provided using the [MUI Theme Provider](https://mui.com/customization/theming 'mui.com') + -
+ It can be accessed in components like this: (-- Click to expand --) + + ```tsx + import {useTheme} from '@mui/material/styles'; + + export default function MyComponent(): JSX.Element { + const theme = useTheme(); + + return ( + + + ); + ``` + +
+ +### Testing + +All code should be tested: + +- Pure TypeScript should be tested using unit tests with a 100% coverage. +- UI code should be tested using the react-testing-library. + +### Performance + +New code should be checked for Performance degradation. +Use the Browser Based Profiling Tools (Chrome/Firefox): + +- [React Developer Tools](https://beta.reactjs.org/learn/react-developer-tools) (Profiler) +- Performance insights (Chrome) +- Lighthouse (Chrome) + +### Documentation + +Code should be documented as much as possible. Each class and function should contain a detailed description of what it +does, what inputs it gets and what outputs it produces. Document only functions that require it. Getters and setters for +example don't to be documented unless they do something unconventional. + +### Internationalization + +All text in the application should be internationalized with at least German and English support. To internationalize +texts the [react-i18next](https://react.i18next.com/) framework is used. + +You can add translations in the `locales/-.json5` files. The following code snippets show +how to use a translation in a React-Hook. + +`locales/en-global.json5`: + +```json +{ + "helloWorld": "Hello, World!" +} +``` + +`locales/de-global.json5`: + +```json +{ + "helloWorld": "Hallo, Welt!" +} +``` + +`HelloWorld.tsx`: + +```tsx +import React from 'react'; +import {useTranslation} from 'react-i18next'; + +export default function HelloWorld(): JSX.Element { + const {t} = useTranslation(); + return

{t('helloWorld')}

; +} +``` + +### Accessibility + +The application should conform to modern accessibility (a11y) guidelines. We use +[Lighthouse](https://developer.chrome.com/docs/lighthouse/overview/) to check for a11y problems. During a pull request +a Lighthouse report is automatically generated during the CI checks. + +### Code Style + +Function names, parameters, variables and class members should be written in `camelCase`. The exception for functions +are React-Hooks, which should be written in `PascalCase`. In addition, classes and interfaces should also be written in +`PascalCase`: + +```tsx +function myFunction(myParameter: string) { + const myVariable = myParameter; +} + +function MyHook() { + return
Hello World
; +} + +interface MyInterface { + myMember: string; +} + +class MyClass { + myMember: MyInterface; +} +``` + +Try to use `const` as much as possible and use `let` otherwise. Never use `var`! + +### Imports + +To optimize the final size of the bundle it is important to make imports as granular as possible to allow for the best +dead code removal. This is especially important for the material icons package. + +Example: + +```tsx +// DON'T DO THIS, it will import ALL the material icons into our application: +import {LockIcon} from '@mui/icons-material'; + +// Instead do this, to insure only the used icons are being imported: +import LockIcon from '@mui/icons-material/Lock'; +``` +--- +### Branching Strategy +The development of ESID follows a simplified version of **git-flow**: The `main` branch always contains stable code. +New features and bug fixes are implemented in `feature/*` or `fix/*` branches and are merged to `develop` once they are finished. +When a new milestone is reached, the content of `develop` will be merged to `main` and a tag is created. + +[Github Actions](https://github.com/DLR-SC/ESID/actions) are used for continuous integration. +All pull requests and pushes to `main` and `develop` are built automatically. + +### Git Commit Messages +Commits should start with a Capital letter and should be written in present tense (e.g. __:tada: Add cool new feature__ instead of __:tada: Added cool new feature__). +It's a great idea to start the commit message with an applicable emoji. This does not only look great but also makes you rethink what to add to a commit. +* :tada: `:tada:` when adding a cool new feature +* :wrench: `:wrench:` when refactoring / improving a small piece of code +* :hammer: `:hammer:` when refactoring / improving large parts of the code +* :sparkles: `:sparkles:` when formatting code +* :art: `:art:` improving / adding assets like textures or images +* :rocket: `:rocket:` when improving performance +* :memo: `:memo:` when writing docs +* :beetle: `:beetle:` when fixing a bug +* :green_heart: `:green_heart:` when fixing the CI build +* :heavy_check_mark: `:heavy_check_mark:` when working on tests +* :arrow_up_small: `:arrow_up_small:` when adding / upgrading dependencies +* :arrow_down_small: `:arrow_down_small:` when removing / downgrading dependencies +* :twisted_rightwards_arrows: `:twisted_rightwards_arrows:` when merging branches +* :fire: `:fire:` when removing files +* :truck: `:truck:` when moving / renaming files or namespaces + +A good way to enforce this on your side is to use a `commit-hook`. To do this, paste the following script into `.git/hooks/commit-msg`. + +``` bash +#!/bin/bash + +# regex to validate in commit msg +commit_regex='(:(tada|wrench|hammer|sparkles|art|rocket|memo|beetle|green_heart|arrow_up_small|arrow_down_small|twisted_rightwards_arrows|fire|truck|heavy_check_mark):(.+))' +error_msg="Aborting commit. Your commit message is missing an emoji as described in the contributing guideline." + +if ! grep -xqE "$commit_regex" "$1"; then + echo "$error_msg" >&2 + exit 1 +fi +``` + +And make sure that it is executable: + +``` bash +chmod +x .git/hooks/commit-msg +```