Feat/add architecture documentation

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:

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`).

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
+```

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).