diff --git a/project-docs/DOCKER_CHEAT_SHEET.md b/project-docs/DOCKER_CHEAT_SHEET.md index a8c8458e..47c516c3 100644 --- a/project-docs/DOCKER_CHEAT_SHEET.md +++ b/project-docs/DOCKER_CHEAT_SHEET.md @@ -2,7 +2,7 @@ ## List running containers -``` +```shell docker ps ``` @@ -10,7 +10,7 @@ docker ps In the directory of the `docker-compose.yml`: -``` +```shell docker-compose ps ``` @@ -18,7 +18,7 @@ docker-compose ps `$CONTAINERID` from `docker ps`. -``` +```shell docker restart $CONTAINERID ``` @@ -26,7 +26,7 @@ docker restart $CONTAINERID `$PROGRAM` can be any program that is installed in the container `bash`, `sh`, `node`, `curl`... -``` +```shell docker exec -it $CONTAINERID $PROGRAM ``` @@ -34,7 +34,7 @@ docker exec -it $CONTAINERID $PROGRAM This removes unused images, networks, ... from your system. -``` +```shell docker system prune ``` diff --git a/project-docs/SCHOOL_IDENTIFIERS.md b/project-docs/SCHOOL_IDENTIFIERS.md index ed9d8c85..fb453799 100644 --- a/project-docs/SCHOOL_IDENTIFIERS.md +++ b/project-docs/SCHOOL_IDENTIFIERS.md @@ -3,7 +3,7 @@ To identify schools we use their license plates. | City | School | License- | plate | | --- | --- | --- | --- | | Aachen | KFH NRW | AC | KF | -| Aachen | Theolog. HS | AC | FK | +| Aachen | Theolog. HS | AC | FK | | Aachen | Fachhochschule | AC | FH | | Aachen | MuHo | AC | HM | | Aachen | Rheinisch-Westf. TH | AC | TH | diff --git a/project-docs/SETUP.md b/project-docs/SETUP.md index bf0cdab0..43b469ea 100644 --- a/project-docs/SETUP.md +++ b/project-docs/SETUP.md @@ -5,7 +5,7 @@ * [SSH](https://docs.gitlab.com/ee/ssh/README.html) * [Git](https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html) * [Docker](https://docs.gitlab.com/ee/user/project/container_registry.html) & Docker-Compose -* Node.js & NPM - be sure to install the current LTS version, might need a [PPA](https://github.com/nodesource/distributions/blob/master/README.md#installation-instructions) +* Node.js & NPM - be sure to install the "Dubnium" (10.x) LTS version, might need a [PPA](https://github.com/nodesource/distributions/blob/master/README.md#installation-instructions) or use NVM * [NVM](https://github.com/creationix/nvm#installation) - if you want to use multiple different versions of node Example for Debian based distributions: @@ -16,14 +16,19 @@ apt install ssh git docker docker-compose nodejs ## IDE - recommended choices -* [Webstorm](https://www.jetbrains.com/webstorm/download/) - Free license for academic purposes * [VSCode](https://code.visualstudio.com/) +* [Webstorm](https://www.jetbrains.com/webstorm/download/) - Educational or OpenSource License **cannot** be used ## Optional helpful tools * Curl - for executing HTTP requests on the command line * Postman or Insomnia - for executing HTTP requests with a GUI +## Before you start (Windows only) + +As we are working on LF line-endings only, make sure your editior or IDE does not introduce CRLF line-endings. +Depending on your preferred settings you could consider applying `git config core.eol lf` and `git config core.autocrlf input` within our reposiories. + ## Clone starter repositories * [Minimal deployment](https://gitlab.com/openstapps/minimal-deployment) - contains backend, database, minimal connector, copy (from api) and app diff --git a/project-docs/workflow/COMMITS.md b/project-docs/workflow/COMMITS.md index 15fb0385..c1128c33 100644 --- a/project-docs/workflow/COMMITS.md +++ b/project-docs/workflow/COMMITS.md @@ -50,7 +50,7 @@ The result of those commit guidelines is a concise and clear history of the deve Another advantage is the automatic [generation](https://www.npmjs.com/package/conventional-changelog-cli) of a changelog that gives an overview of the changes. -``` +```shell conventional-changelog -p angular -i CHANGELOG.md -s -r 0 ``` diff --git a/project-docs/workflow/DOCUMENTATION.md b/project-docs/workflow/DOCUMENTATION.md index 437284e6..bd156d35 100644 --- a/project-docs/workflow/DOCUMENTATION.md +++ b/project-docs/workflow/DOCUMENTATION.md @@ -1,6 +1,6 @@ # Documentation -Every projects need a `README.md` as a standardized entry of information about the scope of a [project](PROJECT.md) and how to install and execute it. +Every projects need a `README.md` as a standardized entry of information about the scope of a [project](PROJECT.md) and how to install and execute it. ## Inline (code) documentation @@ -10,7 +10,7 @@ Code is annotated with [TypeDoc](https://typedoc.org/), which then can be used t Please follow these guidelines to reduce redundance: -* The purpose of inline documentation is to explain what the line of code actually does without explaining syntax or external references. Example: +* The purpose of inline documentation is to explain what the line of code actually does without explaining syntax or external references. Example: ```typescript // extend the template by the properties of the base template @@ -36,10 +36,12 @@ async get(key: string): Promise { return entry; } ``` + ### Inline Comments `//` * Start inline comments with a lowercase letter and a space after the `//` * Place the comment above the line that it is referencing + ```typescript // lorem ipsum const lorem; @@ -55,10 +57,11 @@ const lorem; * Document all parameters in functions using `@param` * `@param` must not contain a type annotation, just `@param name description` * Do not include `@return`, as it is redundant information + ```typescript /** * Short summary of the function, without a period - * + * * This is a very long description, that could never possibly fit on one line, nor could it * be read in a short amount of time. Because we can use multiple sentences here, we can actually * use a period. @@ -70,7 +73,7 @@ function fun(foo: number): Foo { ## `CONTRIBUTING.md` -Every project can have a `CONTRIBUTING.md` which explains how to contribute to the project either just by issues or code contributions. +Every project can have a `CONTRIBUTING.md` which explains how to contribute to the project either just by issues or code contributions. ## Issue templates diff --git a/project-docs/workflow/LICENSING.md b/project-docs/workflow/LICENSING.md index b452439c..ff65fd02 100644 --- a/project-docs/workflow/LICENSING.md +++ b/project-docs/workflow/LICENSING.md @@ -10,7 +10,7 @@ Copy the license from [projectmanagement](../../LICENSE) or the [official standa According to the GPLv3 guidelines for [adding the license to a new program](http://www.gnu.org/licenses/gpl-3.0-standalone.html#howto) a license note should be added at the beginning of each source file. -``` +```typescript /* * Copyright (C) StApps * This program is free software: you can redistribute it and/or modify it @@ -30,14 +30,16 @@ According to the GPLv3 guidelines for [adding the license to a new program](http ### New Files The `` should be inserted with the current year. E.g.: -``` + +```typescript * Copyright (C) 2019 StApps ``` ### Updating Files If the file is updated in a new year after its creation, the `` should be appended as a comma seperated list with spaces in between. E.g.: -``` + +```typescript * Copyright (C) 2018, 2019, 2021 StApps ``` diff --git a/project-docs/workflow/MERGING.md b/project-docs/workflow/MERGING.md index dd6901bd..aa1c15ea 100644 --- a/project-docs/workflow/MERGING.md +++ b/project-docs/workflow/MERGING.md @@ -1,6 +1,6 @@ # Merging & merge requests -Once development of an [issue](ISSUES.md) on a [branch](BRANCHING.md) is completed the merge request becomes relevant. It also can be used during development for continuous reviews and iterative improvements. +Once development of an [issue](ISSUES.md) on a [branch](BRANCHING.md) is completed the merge request becomes relevant. It also can be used during development for continuous reviews and iterative improvements. A merge request can also gather the work of multiple issues. diff --git a/project-docs/workflow/PUBLISHING.md b/project-docs/workflow/PUBLISHING.md index cbf8c325..1f9204e4 100644 --- a/project-docs/workflow/PUBLISHING.md +++ b/project-docs/workflow/PUBLISHING.md @@ -4,7 +4,7 @@ All projects that use the [OpenStApps configuration](https://gitlab.com/openstapps/configuration) and implement the automatic publishing via GitLab CI can simply be published to the NPM registry by using the appropriate job. It uses the `NPM_AUTH_TOKEN` that is a [protected variable](https://gitlab.com/groups/openstapps/-/settings/ci_cd) of the OpenStApps group. To trigger this job, a new tag has to be created (on the master branch): -### Use current [master branch](BRANCHING.md): +### Use current [master branch](BRANCHING.md) ```shell git checkout master @@ -16,7 +16,7 @@ git pull ```shell npm version (major|minor|patch) ``` - + After these steps there should 2 new commits: * A version commit