Theaninova/openstapps
1
0
Fork 0
mirror of https://gitlab.com/openstapps/openstapps.git synced 2026-01-21 09:03:02 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: fix markdown errors and update

Browse Source
This commit is contained in:
Rainer Killinger
2020-10-30 17:45:49 +01:00
parent 5f34bc900c
commit ccb1b56a0f
8 changed files with 29 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
project-docs/DOCKER_CHEAT_SHEET.md
View File

@@ -2,7 +2,7 @@
## List running containers ## List running containers
``` ```shell
docker ps docker ps
``` ```
@@ -10,7 +10,7 @@ docker ps
In the directory of the `docker-compose.yml`: In the directory of the `docker-compose.yml`:
``` ```shell
docker-compose ps docker-compose ps
``` ```
@@ -18,7 +18,7 @@ docker-compose ps
`$CONTAINERID` from `docker ps`. `$CONTAINERID` from `docker ps`.
``` ```shell
docker restart $CONTAINERID 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`... `$PROGRAM` can be any program that is installed in the container `bash`, `sh`, `node`, `curl`...
``` ```shell
docker exec -it $CONTAINERID $PROGRAM docker exec -it $CONTAINERID $PROGRAM
``` ```
@@ -34,7 +34,7 @@ docker exec -it $CONTAINERID $PROGRAM
This removes unused images, networks, ... from your system. This removes unused images, networks, ... from your system.
``` ```shell
docker system prune docker system prune
``` ```

2
project-docs/SCHOOL_IDENTIFIERS.md
View File

@@ -3,7 +3,7 @@ To identify schools we use their license plates.
| City | School | License- | plate | | City | School | License- | plate |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| Aachen | KFH NRW | AC | KF | | Aachen | KFH NRW | AC | KF |
| Aachen | Theolog. HS | AC | FK | | Aachen | Theolog. HS | AC | FK |
| Aachen | Fachhochschule | AC | FH | | Aachen | Fachhochschule | AC | FH |
| Aachen | MuHo | AC | HM | | Aachen | MuHo | AC | HM |
| Aachen | Rheinisch-Westf. TH | AC | TH | | Aachen | Rheinisch-Westf. TH | AC | TH |

9
project-docs/SETUP.md
View File

@@ -5,7 +5,7 @@
* [SSH](https://docs.gitlab.com/ee/ssh/README.html) * [SSH](https://docs.gitlab.com/ee/ssh/README.html)
* [Git](https://docs.gitlab.com/ee/gitlab-basics/start-using-git.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 * [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 * [NVM](https://github.com/creationix/nvm#installation) - if you want to use multiple different versions of node
Example for Debian based distributions: Example for Debian based distributions:
@@ -16,14 +16,19 @@ apt install ssh git docker docker-compose nodejs
## IDE - recommended choices ## IDE - recommended choices
* [Webstorm](https://www.jetbrains.com/webstorm/download/) - Free license for academic purposes
* [VSCode](https://code.visualstudio.com/) * [VSCode](https://code.visualstudio.com/)
* [Webstorm](https://www.jetbrains.com/webstorm/download/) - Educational or OpenSource License **cannot** be used
## Optional helpful tools ## Optional helpful tools
* Curl - for executing HTTP requests on the command line * Curl - for executing HTTP requests on the command line
* Postman or Insomnia - for executing HTTP requests with a GUI * 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 ## Clone starter repositories
* [Minimal deployment](https://gitlab.com/openstapps/minimal-deployment) - contains backend, database, minimal connector, copy (from api) and app * [Minimal deployment](https://gitlab.com/openstapps/minimal-deployment) - contains backend, database, minimal connector, copy (from api) and app

2
project-docs/workflow/COMMITS.md
View File

@@ -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. 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 conventional-changelog -p angular -i CHANGELOG.md -s -r 0
``` ```

11
project-docs/workflow/DOCUMENTATION.md
View File

@@ -1,6 +1,6 @@
# Documentation # 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 ## 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: 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 ```typescript
// extend the template by the properties of the base template // extend the template by the properties of the base template
@@ -36,10 +36,12 @@ async get<T>(key: string): Promise<T> {
return entry; return entry;
} }
``` ```
### Inline Comments `//` ### Inline Comments `//`
* Start inline comments with a lowercase letter and a space after the `//` * Start inline comments with a lowercase letter and a space after the `//`
* Place the comment above the line that it is referencing * Place the comment above the line that it is referencing
```typescript ```typescript
// lorem ipsum // lorem ipsum
const lorem; const lorem;
@@ -55,10 +57,11 @@ const lorem;
* Document all parameters in functions using `@param` * Document all parameters in functions using `@param`
* `@param` must not contain a type annotation, just `@param name description` * `@param` must not contain a type annotation, just `@param name description`
* Do not include `@return`, as it is redundant information * Do not include `@return`, as it is redundant information
```typescript ```typescript
/** /**
* Short summary of the function, without a period * 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 * 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 * be read in a short amount of time. Because we can use multiple sentences here, we can actually
* use a period. * use a period.
@@ -70,7 +73,7 @@ function fun(foo: number): Foo {
## `CONTRIBUTING.md` ## `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 ## Issue templates

8
project-docs/workflow/LICENSING.md
View File

@@ -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. 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) <year> StApps * Copyright (C) <year> StApps
* This program is free software: you can redistribute it and/or modify it * 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 ### New Files
The `<year>` should be inserted with the current year. E.g.: The `<year>` should be inserted with the current year. E.g.:
```
```typescript
* Copyright (C) 2019 StApps * Copyright (C) 2019 StApps
``` ```
### Updating Files ### Updating Files
If the file is updated in a new year after its creation, the `<year>` should be appended as a comma seperated list with spaces in between. E.g.: If the file is updated in a new year after its creation, the `<year>` should be appended as a comma seperated list with spaces in between. E.g.:
```
```typescript
* Copyright (C) 2018, 2019, 2021 StApps * Copyright (C) 2018, 2019, 2021 StApps
``` ```

2
project-docs/workflow/MERGING.md
View File

@@ -1,6 +1,6 @@
# Merging & merge requests # 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. A merge request can also gather the work of multiple issues.

4
project-docs/workflow/PUBLISHING.md
View File

@@ -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): 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 ```shell
git checkout master git checkout master
@@ -16,7 +16,7 @@ git pull
```shell ```shell
npm version (major|minor|patch) npm version (major|minor|patch)
``` ```
After these steps there should 2 new commits: After these steps there should 2 new commits:
* A version commit * A version commit