From a852cbf97307bd2ad530b88774defebab528c4a7 Mon Sep 17 00:00:00 2001
From: Jumace <Jumace@users.noreply.github.com>
Date: Mon, 4 Mar 2024 16:27:01 +0100
Subject: [PATCH] docs: update documentation

---
 README.md                  | 13 +++---
 docs/ARCHITECTURE.md       | 68 ++++++++++++++++++++---------
 docs/CONTRIBUTE.md         | 85 +++++++++++++++++++++++++++----------
 docs/DEPLOYMENT.md         | 87 +++++++++++++++++++++++++++-----------
 docs/GET_STARTED.md        | 47 ++++----------------
 docs/PROJECT_BACKGROUND.md | 21 ++++-----
 docs/TESTING.md            | 15 +++----
 7 files changed, 203 insertions(+), 133 deletions(-)

diff --git a/README.md b/README.md
index 99176c9..f1761b1 100644
--- a/README.md
+++ b/README.md
@@ -10,24 +10,23 @@
 
 `deven-documentation-skeleton` is built to work with NodeJS. It clones the deven's documentation skeleton in your project, provides information about the documentation coverage and help to you identify and clone the missing chapters.
 
-## :information_source: Table of contents
+## :information_source: Table of contents  <!-- omit in toc -->
 
 - [Deven Documentation Skeleton](#deven-documentation-skeleton)
-  - [:information_source: Table of contents](#information_source-table-of-contents)
 - [:star: Introduction](#star-introduction)
   - [Goals](#goals)
-  - [:file_folder: Documentation Structure](#file_folder-documentation-structure)
+  - [:file\_folder: Documentation Structure](#file_folder-documentation-structure)
   - [Requirements](#requirements)
   - [Installation](#installation)
   - [:rocket: How to use it](#rocket-how-to-use-it)
     - [1. Install](#1-install)
     - [2. Check](#2-check)
     - [3. Update](#3-update)
-- [:white_check_mark: How to test](#white_check_mark-how-to-test)
+- [:white\_check\_mark: How to test](#white_check_mark-how-to-test)
 - [:v: Contribute](#v-contribute)
 - [:bug: Bugs and Issues](#bug-bugs-and-issues)
-- [:page_facing_up: License](#page_facing_up-license)
-- [:green_heart: Code of conduct](#green_heart-code-of-conduct)
+- [:page\_facing\_up: License](#page_facing_up-license)
+- [:green\_heart: Code of conduct](#green_heart-code-of-conduct)
 
 # :star: Introduction
 
@@ -70,6 +69,8 @@ The purpose of this "documentation skeleton" project is to provide a simple way
 - If you use Yarn, then => v1.2.0
 - If you use Npm, then => v8.0.0
 
+If node can't be used in the target project, one can also copy all files under `src/docs` manually into a project and start to use them.
+
 ## Installation
 
 To install the package in your project follow these steps:
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 4a84108..c6bbb42 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,37 +1,65 @@
 # Architecture
 
-<!--
-This chapter should provide the user with as much information as possible about the architecture and overall structure of your project. Please provide a short introduction here.
--->
+The documentation skeleton can be integrated in multiple ways into other projects, the recommended way is to add it as a devDependency.
 
-## Content
+As an npm package the project has also multiple commands that can be executed.
+
+In this document one can find more information about the npm package and command architecture.
+
+## Content <!-- omit in toc -->
 
 - [Architecture](#architecture)
   - [Overall Structure](#overall-structure)
+    - [Entry script](#entry-script)
+    - [The commands](#the-commands)
+    - [Shared](#shared)
   - [Technical Decisions](#technical-decisions)
-  - [APIs](#apis)
 
 ## Overall Structure
 
-<!--
-Please explain the overall structure of your project and how everything works together. You can use screenshots or code snippets to help visualize things like e.g. your folder structure or the project setup. In this chapter you can be as detailed as you like.
--->
+The project consists of multiple parts, in the contribution guide one can find an overview of the [file structure](/docs/CONTRIBUTE.md#📁-file-structure).
+
+### Entry script
+
+The entry script can be found under `bin/index.js`.
+
+This script is a wrapper for the commands implemented under `src/commands`.
+
+Because the script is a wrapper it was decided to leave it in plain JavaScript.
+
+The script imports/requires the commands from the UMD bundle out of the build folder.
+
+The script checks the call parameters and depended on them calls one of the commands.
+
+### The commands
+
+The documentation skeleton project has three different commands to support with your own documentation structure.
+
+The commands are written in TypeScript and with `microbundle` bundled into a UMD module.
+
+Each command has a number of tests, which can be found in the directory `__tests__`.
+
+### Shared
+
+The `shared` folder contains the messages that are used by the different commands to communicate with the user.
 
 ## Technical Decisions
 
-<!--
-In this section you should list all technical things you use like frameworks, tools, languages and provide explanations of why you have chosen them. Think about e.g. what are the main reasons you choose a framework, what are the advantages you need for your project? Try to be as clear as possible so also new joiners understand why your setup is the best for your project.
--->
+The project is bundled to a UMD module with the help of `microbundle`.
+
+As this is an open source project we aim for a test coverage of >90%, experience showed that it good to cover as much as possible with tests.
+
+We use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) and enforce them with a hook that checks the commit message after creation with [commitlint](https://github.com/conventional-changelog/commitlint)
+
+The `pre-push` hook is used to run linting ([ESLint](https://eslint.org/)), formatting ([prettier](https://prettier.io/)) and testing ([Jest](https://jestjs.io/)).
+If any part of the hook is failing the code can not be pushed before the required changes are implemented.
 
-## APIs
+If a work-in-progress should be pushed one can use the `--no-verify` flag on the push command but this bypass should only be used if needed.
 
-<!--
-Please describe briefly how you manage the APIs of your project and how to use them.
+The package uses itself for the documentation, therefore we have multiple `self*` commands.
+To use those commands a build needs to be done beforehand as it is calling the bundled code.
 
-The documentation could:
+The used node version is 18, due to a problem with the `mock-fs` dependency. The dependency is not compatible with node 20 yet.
+Due to that we set the required node version between 16.20.2 and 20.0.0.
 
-- describe the data structures, functions, arguments, return types, classes, payloads, etc., developers can refer to.
-- refer to other existing resources (git repos, websites, etc.)
-- if you are using one or more tools, describe how to install / access / use them
-- how to test the APIs locally
--->
+To make sure that the whole package can still be used by projects that use node >= 20.0.0 we delete the `engines` key out of the `package.json` before a publish happens and restore it afterwards again (see `prepublishOnly` and `postpublish` in `package.json`).
\ No newline at end of file
diff --git a/docs/CONTRIBUTE.md b/docs/CONTRIBUTE.md
index 1b24301..de6367b 100644
--- a/docs/CONTRIBUTE.md
+++ b/docs/CONTRIBUTE.md
@@ -1,19 +1,20 @@
-# Welcome to our docs contributing guide <!-- omit in toc -->
+# Welcome to our docs contributing guide
 
 Thank you for investing your time in contributing to our project! We sincerely appreciate it. :sparkles:.
 Please, read our [Code of Conduct](./CODE_OF_CONDUCT.md) to keep our community approachable and respectable.
 
-## Content
+## Content <!-- omit in toc -->
 
-- [New contributor guide](#new-contributor-guide)
-- [Getting started](#getting-started)
-  - [:file_folder: File Structure](#file_folder-file-structure)
-- [Issues](#issues)
-  - [Create a new issue](#create-a-new-issue)
-  - [Solve an issue](#solve-an-issue)
-    - [Prerequisites](#prerequisites)
-    - [Commits](#commits)
-    - [Branch](#branch)
+- [Welcome to our docs contributing guide](#welcome-to-our-docs-contributing-guide)
+  - [New contributor guide](#new-contributor-guide)
+  - [Getting started](#getting-started)
+    - [:file\_folder: File Structure](#file_folder-file-structure)
+  - [Issues](#issues)
+      - [Create a new issue](#create-a-new-issue)
+    - [Solve an issue](#solve-an-issue)
+      - [Prerequisites](#prerequisites)
+      - [Commits](#commits)
+      - [Branch](#branch)
 
 ## New contributor guide
 
@@ -29,17 +30,20 @@ To get an overview of the project, read the [README](../README.md). Here are som
 ### :file_folder: File Structure
 
     .
+    └── .husky            // contains git hooks
+    └── .github           // GitHub workflows
+    └── assets            // files like images for the documentation
+    └── docs              // documentation of the project
     └── src
         └── __tests__     // Unit test (*.spec.ts)
         └── commands      // CLI's commands classes
         └── shared        // Global configuration and log messages
         └── docs          // the documentation skeleton
-        └── config        // the configuration file blueprint
+        └── root          // the configuration file blueprint
+    └── coverage          // jest coverage report
     └── dist              // build output
     └── bin               // cli entrypoint
-    └── gitlab-ci.yml     // GitLab CI/CD pipeline
     └── CHANGELOG.md      // This file is automatically created by the release stage of the main pipeline. Please don't touch it.
-    └── .releaserc        // semantic-release configuration file
 
 ## Issues
 
@@ -51,7 +55,7 @@ If you spot a problem with the tool or the documentation, please [search if an i
 <summary>How to write a useful issue?</summary>
 <br />
 
-- It should be _reproducible_. It should contain all the istructions needed to reproduce the same outcome.
+- It should be _reproducible_. It should contain all the instructions needed to reproduce the same outcome.
 
 - It should be _specific_. It's important that it addresses one specific problem.
 
@@ -60,28 +64,63 @@ If you spot a problem with the tool or the documentation, please [search if an i
 ### Solve an issue
 
 Scan through our [existing issues](https://git.sinnerschrader.com/deven/documentation-skeleton/-/issues/) to find one that interests you.
-If you find an issue to work on, you are welcome to open a Merge Request with a fix.
+If you find an issue to work on, you are welcome to open a merge request with a fix.
 
 #### Prerequisites
 
-Please, before submitting any merge request, be sure that your branch is passing all the tests.
+Please, before submitting any merge request, be sure that your branch is passing all requirements.
+
+1. Check that all tests are working:
 
 ```bash
 npm run test
 ```
 
-or
+2. Check that there are no linting issues:
 
 ```bash
-yarn test
+npm run lint
 ```
+(the command will also try to fix found issues)
+
+3. Check that the files are formatted:
 
+```bash
+npm run prettier
+```
+(the command will also try to fix found issues)
 #### Commits
 
-The commits must be compliant with with the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/).
+The commits must be compliant with the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/).
 
 #### Branch
 
-For contributions we are using [Gitflow as branching strategy](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow#:~:text=Gitflow%20is%20a%20legacy%20Git,software%20development%20and%20DevOps%20practices.).
-
-#
+We use the [Git-Flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) branching model:
+
+```mermaid
+        gitGraph
+       commit id: "a"
+       commit id: "b"
+       branch develop
+       checkout develop
+       checkout develop
+       branch feature1
+       checkout feature1
+       commit id: "c"
+       checkout develop
+       merge feature1
+       branch feature2
+       checkout feature2
+       commit id: "d"
+       checkout develop
+       merge feature2
+       checkout main
+       merge develop
+       branch "release"
+       checkout release
+       commit id: "1.0.0" tag: "release"
+       checkout main
+       merge release
+       checkout develop
+       merge main
+```
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index f8f0272..224798f 100644
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -1,51 +1,88 @@
 # Deployment
 
-<!--
-This chapter should provide the user with all needed information around the deployment of your project. Please provide a short introduction here.
--->
+The documentation skeleton project will be deployed on every update of the main branch.
 
-## Content
+## Content <!-- omit in toc -->
 
 - [Deployment](#deployment)
   - [Tooling](#tooling)
+    - [Release Please](#release-please)
+    - [Conventional Commit Messages](#conventional-commit-messages)
   - [How to deploy](#how-to-deploy)
   - [Versioning](#versioning)
-  - [Release Management](#release-management)
   - [Deployment Schedule](#deployment-schedule)
   - [Support](#support)
 
 ## Tooling
 
-<!--
-Please explain what kind of tools you use for your deployment, why you have choosen them and how to work with them.
--->
+This project uses release-please and conventional commit messages for automated release creation and deploys the package to the npm registry.
+
+We use the [Git-Flow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow) branching model:
+
+```mermaid
+        gitGraph
+       commit id: "a"
+       commit id: "b"
+       branch develop
+       checkout develop
+       checkout develop
+       branch feature1
+       checkout feature1
+       commit id: "c"
+       checkout develop
+       merge feature1
+       branch feature2
+       checkout feature2
+       commit id: "d"
+       checkout develop
+       merge feature2
+       checkout main
+       merge develop
+       branch "release"
+       checkout release
+       commit id: "1.0.0" tag: "release"
+       checkout main
+       merge release
+       checkout develop
+       merge main
+```
+
+### Release Please
+
+Release Please automates CHANGELOG generation, the creation of GitHub releases, and version bumps for your projects. Release Please does so by parsing the git history, looking for Conventional Commit messages, and creating release PRs.
+
+The tool runs on every update on the `main` branch and creates a release PR which needs to be manually be merged to create the release.
+
+The updated `main` branch then needs to be merged back, please use rebase, into the `develop` branch.
+
+Due to the open source nature of this project it was decided it is best to have a `develop` branch to test all new features together before an official release is created.
+
+### Conventional Commit Messages
+
+We use [Conventional Commit messages](https://www.conventionalcommits.org/en/v1.0.0/) to be able to create changelog and version bumps automatically.
+
+We have a pre-push hook installed that uses [commit lint](https://github.com/conventional-changelog/commitlint) to verify the commits messages are following the conventional commit message standard.
 
 ## How to deploy
 
-<!--
-In this section you should discribe the deployment process for your project. Think about how developers  who are unfamiliar with the project can deploy it to the respective enviroments.
--->
+One needs to create a new PR from `develop` to `main`. Once the PR is approved and merged the GitHub workflow `release` will be started.
 
-## Versioning
+The `release` workflow will first run the tests and after they were successful a new release branch is created together with a PR from the release branch into `main`.
 
-<!--
-Please describe briefly how you manage the versioning of your project.
--->
+Lastly a notification for the internal slack channel is created.
 
-## Release Management
+The newly created release PR needs to be manually merged into main to finish the package creation and release publishing.
+
+After the release PR is merged the `develop` branch also needs to be updated by rebasing it onto the `main` branch.
+
+## Versioning
 
-<!--
-If you have a release management setup in place, please describe the process and who to contact if support is needed.
--->
+Please see [conventional commit messages](#conventional-commit-messages)
 
 ## Deployment Schedule
 
-<!--
-Please write down your deployment schedule. Consider using screenshots or graphs for better visualization.
--->
+There is no deployment schedule. A new release is created whenever we have multiple new small features or a new big feature that we want to release.
 
 ## Support
 
-<!--
-If someone needs support while deploying your project, please list the possible contact persons or communication channels where people can get support.
--->
+If you need support with the release process please [create an issue](https://github.com/deven-org/hamster/issues) or get in touch with [Jumace](https://github.com/Jumace).
diff --git a/docs/GET_STARTED.md b/docs/GET_STARTED.md
index ab844e8..5f5e586 100644
--- a/docs/GET_STARTED.md
+++ b/docs/GET_STARTED.md
@@ -1,51 +1,22 @@
 # Get Started
 
-<!--
-This chapter is all about welcoming your new colleague in your project and helping them to learn about all the necessary organizational aspects. Please provide a nice and welcoming introduction here.
--->
+For a quick overview check out the [Readme](/README.md).
 
-## Content
+For new joiners the [contribution guide](./CONTRIBUTE.md) is a good starting point.
+
+One can also get more information about the [architecture](./ARCHITECTURE.md) and [deployment](./DEPLOYMENT.md).
+
+## Content <!-- omit in toc -->
 
 - [Get Started](#get-started)
-  - [Team Overview](#team-overview)
-  - [Regular Meetings](#regular-meetings)
   - [Communication Channels](#communication-channels)
-  - [Access Checklist](#access-checklist)
   - [How to get support](#how-to-get-support)
-  - [Link Archive](#link-archive)
-
-## Team Overview
-
-<!--
-We encourage you to use this section to provide information about the team your new colleague will work in. Please also mark the people who are main contact persons for overall organisational tasks, e.g. Scrum Master. You can list the names, disciplines, also add photos if you like. Since most projects work mainly remote it's nice to have some names and faces in place.
--->
-
-## Regular Meetings
-
-<!--
-In this section you can add a list of regular meetings like scrum ceremonies or review meetings. You could also add a screenshot of your team calender if you have something in place.
--->
 
 ## Communication Channels
 
-<!--
-Please list the different communication channels you use within your project, like Slack groups or mailing lists. If necessary provide details on whom each communication channel adresses and how to access them.
--->
-
-## Access Checklist
-
-<!--
-Please provide a complete list with all the accesses that your new colleage will need when working in your project. Every entry should have a description on how to recieve access and a contact person or link to access more information if needed.
--->
+Communication happens over [GitHub issues](https://github.com/deven-org/documentation-skeleton/issues).
 
 ## How to get support
 
-<!--
-This section should provide the new joiner with all possible ways to get further support, like a link to the UHD Slack channel or contact persons. This should also include a link to the Code of Conduct.
--->
-
-## Link Archive
-
-<!--
-Here you can paste all the links with short, explanatory titles that can be useful for others. E.g. links to design files, Confluence or Wiki Pages, Ticket Guidelines etc.
--->
+If support is needed please get in touch with [Jumace](https://github.com/Jumace).
+Please note our [Code of Conduct](./CODE_OF_CONDUCT.md) when a support request is created.
\ No newline at end of file
diff --git a/docs/PROJECT_BACKGROUND.md b/docs/PROJECT_BACKGROUND.md
index 13ddcd2..1849a6a 100644
--- a/docs/PROJECT_BACKGROUND.md
+++ b/docs/PROJECT_BACKGROUND.md
@@ -1,10 +1,8 @@
 # Project Background
 
-<!--
-This chapter should provide the user with information about historical decisions, where you have started from and what you've learned until now. This chapter is optional, but the longer your project is active the more important it becomes. We highly encourage you to use it as an opportunity to record all your knowledge and experiences you gathered in this project. Please provide a short introduction here.
--->
+The documentation skeleton is a guide to improve your documentation.
 
-## Content
+## Content <!-- omit in toc -->
 
 - [Project Background](#project-background)
   - [Background](#background)
@@ -13,18 +11,15 @@ This chapter should provide the user with information about historical decisions
 
 ## Background
 
-<!--
-Please write down when and how everything started. What were the main ideas, how many people were included, what was the goal of the project?
--->
+The project was born out of the idea to make documentation creation easier for developers.
+It is a starting point for documentations and with the added comments in each file it helps developers to get an idea what can or should be documented.
 
 ## Strategy
 
-<!--
-This section should be all about the strategy your project is based on an how it might have changed in the past. You could also use e.g. links to presentations and files or add screenshots to visualize the goald you are aiming for and how you want to achieve it.
--->
+The documentation skeleton can by installed as an npm package but is not limited to that.
+The idea is that any tech project regardless of the technologies used can use and profit from the documentation skeleton.
 
 ## Tech Changes
 
-<!--
-Have you ever had major changes regarding tech decision? Maybe you've started by using React but later on changed to a different framework that fits better to the projects needs? Or you changed from one naming convention to another? Explain why these decisions were made.
--->
+The first few packages of the documentation skeleton were published in the npm registry of GitHub.
+From version 2.1.0 on the package is now available in the [registry of npmjs.com](https://www.npmjs.com/package/@deven-org/documentation-skeleton).
\ No newline at end of file
diff --git a/docs/TESTING.md b/docs/TESTING.md
index 919f027..d659894 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -2,31 +2,30 @@
 
 This chapter provides the user with all needed information around testing within this project.
 
-## Content
+## Content <!-- omit in toc -->
 
 - [Testing](#testing)
-  - [Content](#content)
   - [Tooling](#tooling)
-  - [Jest](#jest)
-  - [mock-fs](#mock-fs)
-  - [jest-mock-process](#jest-mock-process)
+    - [Jest](#jest)
+    - [mock-fs](#mock-fs)
+    - [jest-mock-process](#jest-mock-process)
   - [How to write tests](#how-to-write-tests)
   - [How to run tests](#how-to-run-tests)
 
 ## Tooling
 
-## Jest
+### Jest
 
 As _testing framework_ we are currently using [Jest](https://jestjs.io/).
 
-## mock-fs
+### mock-fs
 
 Since the CLI is mainly reading and writing files, the tests are using the _mock-fs_ module to allow Node's built-in fs module to be backed temporarily by an in-memory, mock file system.
 This lets you run tests against a set of mock files and directories instead of lugging around a bunch of test fixtures.
 
 [Read more here](https://github.com/tschaub/mock-fs).
 
-## jest-mock-process
+### jest-mock-process
 
 The CLI will be most probably used also in CI/CD pipelines. Therefore the _process exit-codes_ are very important.
 The _jest-mock-process_ module mocks the Node's process properties in Jest making them easily testable.