docs: add worklow docs

project-docs/DOCKER_CHEAT_SHEET.md

@@ -0,0 +1,43 @@
+# Docker cheat sheet
+
+## List running containers
+
+```
+docker ps
+```
+
+## List running containers of a `docker-compose.yml`
+
+In the directory of the `docker-compose.yml`:
+
+```
+docker-compose ps
+```
+
+## Restart container
+
+`$CONTAINERID` from `docker ps`.
+
+```
+docker restart $CONTAINERID
+```
+
+## Run program in container
+
+`$PROGRAM` can be any program that is installed in the container `bash`, `sh`, `node`, `curl`...
+
+```
+docker exec -it $CONTAINERID $PROGRAM
+```
+
+## Tidy system
+
+```
+docker system prune
+```
+
+## Further resources
+
+* [An Exhaustive Guide to Writing Dockerfiles for Node.js Web Apps](https://blog.hasura.io/an-exhaustive-guide-to-writing-dockerfiles-for-node-js-web-apps-bbee6bd2f3c4)
+* [Docker and Node.js Best Practices
+](https://github.com/nodejs/docker-node/blob/master/docs/BestPractices.md)

project-docs/workflow/BRANCHING.md

@@ -0,0 +1,25 @@
+# Branching model
+
+## Possible branch names
+
+* `master`
+* `develop`
+* `$ID-$TITLE`
+
+### `master`
+
+Current productive version of a project resides on the `master` branch.
+
+### `develop`
+
+The upcoming productive version - current development version - resides on the `develop` branch. The `develop` branch is unnecessary in smaller projects when the development is not too fast.
+
+The `master` branch needs to be updated with a fast forward merge after every release in projects that have a `develop` branch.
+
+### `$ID-$TITLE`
+
+Development of features, bugfixes or refactoring is done in branches referencing an issue that follow the naming convention `$ID-$TITLE` where `$ID` is the number of the issue and `$TITLE` is the sluggified title of the issue. The [issues](ISSUES.md) integration of GitLab has a feature that creates such a branch and an accompanying merge request.
+
+## Further resources
+
+* [Git - A successful Git branching model](http://nvie.com/posts/a-successful-git-branching-model/)

project-docs/workflow/CODING.md

@@ -0,0 +1,18 @@
+# Coding style
+
+These guidelines are meant for TypeScript based project but can be adapted for projects that are developed in other languages as well.
+
+## Configuration
+
+Consistent code structure and style is ensured by using [`@openstapps/configuration`](https://gitlab.com/openstapps/configuration/blob/master/README.md). It contains configuration files for your editor, the TypeScript compiler and TSLint.
+
+## Comments
+
+Plenty of inline comments should be used to make it easier to understand what the code is doing.
+
+Inline comments should not explain what code from external projects is doing. Add missing documentation to those external projects.
+
+## Further resources
+
+* [Commit guidelines](COMMITS.md)
+* [TypeScript coding guidelines](https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines)

project-docs/workflow/COMMITS.md

@@ -0,0 +1,59 @@
+# Commit guidelines
+
+## Template
+
+Commit messages should match the following template:
+
+> `TYPE`: `MESSAGE`
+> 
+> `DESCRIPTION`
+
+### `TYPE`
+
+`TYPE` can have one of the following values:
+
+| value | meaning |
+| --- | --- |
+| build | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) |
+| ci | Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) |
+| docs | Documentation only changes |
+| feat | A new feature |
+| fix | A bug fix |
+| perf | A code change that improves performance |
+| refactor | A code change that neither fixes a bug nor adds a feature |
+| style | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) |
+| test | Adding missing tests or correcting existing tests |
+
+These are the [types](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#type), that angular uses. They are easily adaptable for all TypeScript based web related projects.
+
+### `MESSAGE`
+
+`MESSAGE` should complete a sentence that starts with "This commit will...".
+
+The first line of the commit message should not be longer than 50 chars overall.
+
+### `DESCRIPTION`
+
+`DESCRIPTION` can contain a longer description of the commit. Each line should not be longer than 70 chars. New lines can be used to structure the description.
+
+To reference or close [issues](ISSUES.md) GitLab [keywords](https://docs.gitlab.com/ce/user/project/issues/automatic_issue_closing.html) can be used in the last line(s) of the description:
+
+> Fixes #42
+
+or
+
+> References #42
+
+## Advantages
+
+The result of those commit guidelines is a concise and clear history of the development.
+
+Another advantage is the automatic [generation](https://www.npmjs.com/package/conventional-changelog-cli) of a changelog that gives an overview of the changes.
+
+```
+conventional-changelog -p angular -i CHANGELOG.md -s -r 0
+```
+
+## Further resources
+
+* [Versioning](VERSIONING.md)

project-docs/workflow/DOCUMENTATION.md

@@ -0,0 +1,50 @@
+# 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. 
+
+## Inline (code) documentation
+
+Code is annotated with [TypeDoc](https://typedoc.org/), which then can be used to generate complete documentations of the API of the code.
+
+### Guidelines
+
+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: 
+
+```typescript
+// extend the template by the properties of the base template
+templateBase.properties = mergeObjects(
+  templateBase.properties,
+  templates['base.template.json'].mappings._default_.properties
+);
+```
+
+* Follow the [recommendations](http://typedoc.org/guides/doccomments/) of `typedoc`, because it is used to generate documentation. Do not denote the types again in the documentation (`@param` and `@returns`), because they are already "documented" in the code itself. Beispiel:
+
+```typescript
+/**
+ * Gets a value from the storage using the provided key
+ *
+ * @param key Unique identifier of the wanted resource in storage
+ */
+async get<T>(key: string): Promise<T> {
+  const entry = await this.storage.get(key);
+  if (!entry) {
+    throw new Error('Value not found.');
+  }
+  return entry;
+}
+```
+
+## `CONTRIBUTING.md`
+
+Every project can have a `CONTRIBUTING.md` which explains how to contribute to the project either just by issues or code contributions. 
+
+## Issue templates
+
+The path `.gitlab/issue_templates` can contain markdown files which act as templates for issues. These are available as an options during issue creation and just have to be filled by the creator of the issue. They act as orientation which information need sto be provided.
+
+## Further resources
+
+* [GitLab issue templates](https://gitlab.com/help/user/project/description_templates.md)

project-docs/workflow/ISSUES.md

@@ -0,0 +1,9 @@
+# Issues
+
+Regardless of scope - bug, feature, discussion - technical or organisational - everything is an issue.
+
+Issues keep a discussion of the topic, are related to a [branch](BRANCHING.md), keep track of the progress, link to related issues and streamline the process of development.
+
+## Further resources
+
+* [Always start with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/)

project-docs/workflow/MERGING.md

@@ -0,0 +1,11 @@
+# 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. 
+
+A merge request can also gather the work of multiple issues.
+
+Merge requests are used to merge the changes to the main branches (`master`, `develop`). Every merge request needs to be reviewed/commented by at least 2 other developers before they can be accepted. This ensure that all guidelines are followed and that the scope of the issue is matched.
+
+## Further resources
+
+* [Commits](COMMITS.md)

project-docs/workflow/PROJECT.md

@@ -0,0 +1,37 @@
+# Project
+
+A project is an entity that solves a specific task.
+
+Abstractable components of multiple projects should be extracted into another new project.
+
+Node.js projects are published on NPMjs.com in the `@openstapps` group.
+
+## Structure
+
+Node.js/TypeScript based projects should employ the following structure:
+
+```
+src/                  Sources
+test/                 Test files
+lib/                  Compiled sources
+  cli.js              cli tool
+  index.js            API (classes, function, constants, ...)
+  index.d.ts          TypeScript definitions for API
+.editorconfig
+.gitignore            List of files that should be ignored by git
+.npmignore            List of files that should be ignored by npm
+package.json          Package description
+package-lock.json     Meta file, that fixates dependencies
+README.md             Description of project, entry point for documentation
+tsconfig.json         TypeScript configuration
+tslint.json           TSLint configuration
+```
+
+### `@openstapps/configuration`
+
+For the contents and purpose of `.editorconfig`, `tsconfig.json` and `tslint.json` refer to `@openstapps/configuration`.
+
+## Further resources
+
+* [Coding style](CODING.md)
+* [Versioning](VERSIONING.md)

project-docs/workflow/VERSIONING.md

@@ -0,0 +1,15 @@
+# Versioning guidelines
+
+We use semantic version through `npm`.
+
+* `npm version patch`: For fixes/patches
+* `npm version minor`: For new features
+* `npm version major`: For breaking changes in the API
+
+Or directly with `git tag vMAJOR.MINOR.PATCH`.
+
+This tag is set on the `develop`- (if present) or on the `master`-[branch](BRANCHING.md).
+
+## Further resources
+
+* [Commit guidelines](COMMITS.md)