diff --git a/README.md b/README.md index 7256cd36..873393d4 100644 --- a/README.md +++ b/README.md @@ -6,226 +6,120 @@

-# ESID - Epidemiologisches Simulationstool für den Infektionsschutz in Deutschland -ESID is a visualization of infectious disease propagation developed at the [German Aerospace Center (DLR)](https://www.dlr.de/). -It allows displaying historical data, as well as analyzing simulation results of pandemics. +--- +[![REUSE](https://api.reuse.software/badge/github.com/DLR-SC/ESID)](https://api.reuse.software/info/github.com/DLR-SC/ESID) +[![Coverage Status](https://coveralls.io/repos/github/DLR-SC/ESID/badge.svg?branch=develop)](https://coveralls.io/github/DLR-SC/ESID?branch=develop) +[![documentation](https://img.shields.io/badge/Docs-online-34D058.svg)](docs/README.md) +[![license](https://img.shields.io/github/license/DLR-SC/ESID.svg)](LICENSE) +# ESID - Epidemiological Scenarios for Infectious Diseases +> 📘 **Abstract** +> ESID is a visual analytics tool to visualize and compare scenarios of infectious disease propagation developed at the [German Aerospace Center (DLR)](https://www.dlr.de/). +> It allows displaying historical data, as well as analyzing simulation results of pandemic scenarios in multiple, connected views across spatial and temproal domains. + + ## Table of Contents - [Features](#features) +- [Quickstart Guide](#quickstart-guide) - [Developer Documentation](#developer-documentation) - [Contributing to ESID](#contributing-to-esid) - - [Branching Guidelines](#branching-guidelines) - - [Git Commit Messages](#git-commit-messages) - - [Forking ESID](#forking-esid) - [Contributor Covenant Code of Conduct](#contributor-covenant-code-of-conduct) - - [Our Pledge](#our-pledge) - - [Our Standards](#our-standards) - - [Our Responsibilities](#our-responsibilities) - - [Scope](#scope) - - [Enforcement](#enforcement) - - [Attribution](#attribution) -- [Current Contributors](#current-contributors) - - [Previous Contributors](#previous-contributors) +- [Contributors](#contributors) - [License](#license) +--- ## Features -You can find a list of the latest changes in the [changelog](frontend/docs/changelog/changelog-en.md). +- Data Cards for direct comparison of key values between scenarios. +- District overview map to compare the spatial development of scenarios. +- Line chart with date selection and uncerainty display to compare temporal changes in scenario values +- Inter-connected views adapting to context and selected filters +> [!TIP] +> You can find a list of the latest changes in the [changelog](/frontend/docs/changelog/changelog-en.md).[^changelog-de] -## Developer Documentation -You can find the developer documentation for the front- and backend in the corresponding folders: -- [Backend Developer Documentation](backend/README.md) -- [Frontend Developer Documentation](frontend/README.md) +[^changelog-de]: The changelog is also available in german [here](/frontend/docs/changelog/changelog-de.md). -## Contributing to ESID -Whenever you encounter a :beetle: **bug** or have :tada: **feature request**, -report this via [Github issues](https://github.com/DLR-SC/ESID/issues). - -We are happy to receive contributions to ESID in the form of **pull requests** via Github. -Feel free to fork the repository, implement your changes and create a merge request to the `develop` branch. -There is a [forking guide](#forking-esid) available to get you started! - -### Branching Guidelines -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 +## Quickstart Guide +> [!IMPORTANT] +To build 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/) + +First, clone this repository to your computer: +```bash +git clone git@github.com:DLR-SC/ESID.git +cd ESID +git checkout develop ``` +> [!NOTE] +> The `develop` branch contains our latest developed features as outlined in our [Branching Strategy](/frontend/README.md#branching-strategy). -And make sure that it is executable: +Next, initialize the project by downloading and installing its dependencies: +```bash +cd frontend +npm install +``` -``` bash -chmod +x .git/hooks/commit-msg +Once the dependencies are installed you can launch it locally with: +```bash +npm run start ``` +This will host a server at [localhost:8080](http://localhost:8080/), where the website will be displayed. -### Forking ESID -This is pretty straight-forward. Just click the **Fork** button on the top right of this page. -Then clone the forked repository, perform your changes, push to a feature branch and create a pull request to ESID's develop branch. +> [!TIP] +> For further information please check the [Developer Documentation](#developer-documentation) below. -``` bash -git clone git@github.com:/ESID.git -cd ESID -git remote add upstream git@github.com:DLR-SC/ESID.git -git checkout develop +## Developer Documentation +You can find the developer documentation for the front- and backend in the corresponding folders: +- [Backend Developer Documentation](backend/README.md) +- [Frontend Developer Documentation](frontend/README.md) -git checkout -b feature/your-new-feature -# or -git checkout -b fix/your-bugfix -# ... do and commit your changes! +## Contributing to ESID +> [!IMPORTANT] +> Whenever you encounter a :beetle: **bug** or have a :tada: **feature request**, report this via [Github issues](https://github.com/DLR-SC/ESID/issues). -git push origin feature/your-new-feature -``` +We are always happy to receive contributions to ESID in the form of **pull requests** via Github. +Feel free to fork the repository, add your changes and create a pull request to the `develop` branch. -When there were changes in ESID's develop branch, you will need to merge those to your fork before creating a pull request: +There is a [forking guide in the developer guidelines](frontend/README.md#forking-esid) available to get you started quickly! -``` bash -git fetch upstream -git merge upstream/develop -``` -Then you can create a pull request on GitHub to ESID's develop branch. +## Contributor Covenant Code of Conduct +> [!NOTE] +> Our Code of Conduct can be found [here](CODE_OF_CONDUCT.md). +## Contributors +
+Current Contributors -## Contributor Covenant Code of Conduct -### Our Pledge -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, sex characteristics, gender identity and expression, -level of experience, education, socio-economic status, nationality, personal -appearance, race, religion, or sexual identity and orientation. - -### Our Standards -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or - advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -### Our Responsibilities -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. - -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. - -### Scope -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. - -### Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at martin.kuehn@dlr.de. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. - -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. - -### Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html - -[homepage]: https://www.contributor-covenant.org - -For answers to common questions about this code of conduct, see -https://www.contributor-covenant.org/faq - - -## Current Contributors -German Aerospace Center (DLR): +**German Aerospace Center (DLR):** - Martin Kühn - Jonas Gilg - Luca Spataro - Moritz Zeumer - Pawandeep Kaur-Betz -### Previous Contributors -German Aerospace Center (DLR): +
+
+Previous Contributors + +**German Aerospace Center (DLR):** - Margrit Klitz - Kerem Balci - Selma Dahmani - Laurin Kerkloh -Hochschule für Gestaltung Schwäbisch Gmünd (HfG): +**Hochschule für Gestaltung Schwäbisch Gmünd (HfG):** - Julien Stoll - Valerie Grappendorf -## License -Copyright 2021-2023 German Aerospace Center (DLR) - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 +
-Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. +## License +> [!NOTE] +> Copyright 2021-2023 German Aerospace Center (DLR) +> +> Our license can be found [here](LICENSE). 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..589cf2d4 --- /dev/null +++ b/frontend/docs/Technologies_and_Guidelines.md @@ -0,0 +1,282 @@ +# Technologies and Guidelines + +- [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) + - [Branching Strategy](#branching-strategy) + - [Git Commit Messages](#git-commit-messages) + + +## 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](https://www.typescriptlang.org/)**: Type safety and increasing productivity. +- **[React](https://react.dev/)**: Efficient and robust user interface management. +- **[Redux](https://redux.js.org/)**: Efficient and robust state management. +- **[Material UI](https://mui.com/material-ui/)**: Good looking user interface design and responsive layout. + + +## Guidelines + +> [!TIP] +> 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. +- Use the [linter](/frontend/README.md#linting-code) to follow common best prectices. + + +### 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. + +> [!IMPORTANT] +> 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 where necessary. +- 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 + +> [!IMPORTANT] +> 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) + +> [!NOTE] +> A lighthouse report is automatically generated with every pull request, linking the results of the development branch in the pull request makes the review easier. + + +### 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 + +> [!IMPORTANT] +> 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. + +> [!NOTE] +> 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 +```