Merge pull request #1 from NewTec-GmbH/release/v1.0.x

Release v1.0.0

.github/workflows/documentation.yml

@@ -0,0 +1,75 @@
+name: documentation
+
+# Controls when the action will run.
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: [main]
+  release:
+    # A release, pre-release, or draft of a release is published.
+    types: [published]
+  # Allows you to run this workflow manually from the Actions tab.
+  workflow_dispatch:
+
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel.
+jobs:
+  # The introduction just shows some useful informations.
+  intro:
+    # The type of runner that the job will run on.
+    runs-on: ubuntu-latest
+    # Steps represent a sequence of tasks that will be executed as part of the job.
+    steps:
+      - run: echo "The job was automatically triggered by a ${{ github.event_name }} event."
+      - run: echo "The name of the branch is ${{ github.ref }} and the repository is ${{ github.repository }}."
+
+
+  # The build job will build the documentation.
+  build:
+    # The type of runner that the job will run on.
+    runs-on: ubuntu-latest
+    needs: intro
+    permissions:
+      contents: write
+
+    # Steps represent a sequence of tasks that will be executed as part of the job.
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: pip
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '16'
+          cache: npm
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          npm install
+
+      - name: Sphinx build
+        run: |
+          sphinx-build doc _build --fail-on-warning
+
+      # Add the .nojekyll file
+      - name: nojekyll
+        if: ${{ github.event_name == 'push' }}
+        run: |
+          touch _build/.nojekyll
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true

.gitignore

@@ -0,0 +1,2 @@
+_build/
+node_modules/

.vscode/tasks.json

@@ -0,0 +1,101 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Python Requirements",
+            "type": "shell",
+            "command": [
+                "pip",
+                "install",
+                "-r",
+                "requirements.txt"
+            ],
+            "group": {
+                "kind": "requirements"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "NPM Requirements",
+            "type": "shell",
+            "command": [
+                "npm",
+                "install"
+            ],
+            "group": {
+                "kind": "requirements"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Install all requirements",
+            "type": "shell",
+            "dependsOrder": "sequence",
+            "dependsOn": [
+                "Python Requirements",
+                "NPM Requirements"
+            ],
+            "group": {
+                "kind": "requirements"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Build",
+            "type": "shell",
+            "command": [
+                "sphinx-build",
+                "doc",
+                "_build",
+                "--fail-on-warning"
+            ],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "problemMatcher": [],
+            "presentation": {
+                "reveal": "silent"
+            }
+        },
+        {
+            "label": "Clean",
+            "type": "shell",
+            "command": [
+                "sphinx-build",
+                "-M",
+                "clean",
+                "doc",
+                "_build"
+            ],
+            "problemMatcher": []
+        }
+        {
+            "label": "Build and open",
+            "type": "shell",
+            "dependsOrder": "sequence",
+            "dependsOn": [
+                "Build"
+            ],
+            "command": [
+                "open",
+                "_build/index.html"
+            ],
+            "windows": {
+                "command": [
+                    "start",
+                    "_build/index.html"
+                ]
+            },
+            "group": {
+                "kind": "build"
+            },
+            "problemMatcher": [],
+            "presentation": {
+                "reveal": "silent"
+            }
+        }
+    ]
+}

README.md

@@ -0,0 +1,31 @@
+# gitWorkInstructions
+
+[![documentation](https://github.com/NewTec-GmbH/gitWorkInstructions/actions/workflows/documentation.yml/badge.svg)](https://github.com/NewTec-GmbH/gitWorkInstructions/actions/workflows/documentation.yml)
+
+This is the documentation for the NewTec Git Work Instructions. You can find the resulting GitHub Pages in [here](https://newtec-gmbh.github.io/gitWorkInstructions/).
+
+## Used Libraries
+
+Used 3rd party libraries which are not part of the standard Python package:
+
+* [Sphinx](https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html) - Powerful documentation generator that has many great features for writing technical documentation - BSD-2 License
+* [sphinx-rtd-theme](https://sphinx-rtd-theme.readthedocs.io/en/stable/) - Read the Docs theme for Sphinx. - MIT License
+* [sphinx-rtd-dark-mode](https://github.com/MrDogeBro/sphinx_rtd_dark_mode) - Adds a toggleable dark mode to the Read the Docs theme for Sphinx. - MIT License
+* [sphinxcontrib-mermaid](https://github.com/mgaitan/sphinxcontrib-mermaid) - Mermaid diagrams in yours Sphinx powered docs. - BSD-2 License
+* [sphinx-copybutton](https://github.com/executablebooks/sphinx-copybutton) - Add a "copy" button to code blocks in Sphinx. - MIT License
+* [sphinx-togglebutton](https://github.com/executablebooks/sphinx-togglebutton) - Show and hide content with a button in Sphinx. - MIT License
+* [myst-parser](https://github.com/executablebooks/MyST-Parser) - An extended commonmark compliant parser, with bridges to docutils/sphinx. - MIT License
+* [mermaid-js/mermaid-cli](https://github.com/mermaid-js/mermaid-cli) - Command line tool for the Mermaid library. - MIT License
+
+## Issues, Ideas And Bugs
+
+If you have further ideas or you found some bugs, great! Create an [issue](https://github.com/NewTec-GmbH/gitWorkInstructions/issues) or if you are able and willing to fix it by yourself, clone the repository and create a pull request.
+
+## License
+
+The whole source code is published under [BSD-3-Clause](https://github.com/NewTec-GmbH/gitWorkInstructions/blob/main/LICENSE).
+Consider the different licenses of the used third party libraries too!
+
+## Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, shall be licensed as above, without any additional terms or conditions.

doc/_static/css/svg.css

@@ -0,0 +1,3 @@
+object {
+    width: 100%;
+}

doc/branches/branch_types.md

@@ -0,0 +1,154 @@
+# Branches
+
+This page will introduce the naming conventions for the different types of branches and highlight their specific use cases.
+
+## Main branch
+
+The `main` branch is the singular and first branch existing on a new repository.
+It is used to represent the current state of the project, therefore it is most important to keep it in a stable state.
+
+:::{danger}
+Direct work on the `main` branch is forbidden!
+:::
+
+The `main` branch is used to track the latest release version of the project. A release is a traceable version of the project, and therefore the `main` branch can be seen as an overview of the different releases, as seen below:
+
+```{mermaid}
+%%{init: { 'gitGraph': {'showCommitLabel': false}} }%%
+gitGraph
+   commit
+   commit tag: "v1.0.0"
+   commit tag: "v2.0.0"
+   commit tag: "v2.2.0"
+   commit tag: "v3.0.0"
+```
+
+Note that the commits in the figure above are the result of merge operations from [release branches](#release-branches).
+
+:::{hint}
+We use [Semantic Versioning](https://docs.npmjs.com/about-semantic-versioning) to determine the version number of each release.
+:::
+
+## Release branches
+
+Release branches serve as a staging area for the integration of new features and fixes.
+
+A release branch has the prefix `release/` followed by the **future** release version that will be published to main when the work on all features has been completed excluding the patch version: `release/v<major>.<minor>.x`. For example, the branch `release/v2.0.x` contains all the patches belonging to major version 2 and minor version 0.
+
+While the state of the software on a release branch does not necessarily have to be stable, they are not intended to be worked on directly. For this reason, [feature](#feature-branches) and [bugfix](#bugfix-branches) branches are introduced.
+
+### Ready for release
+
+Once all the features planned for the release have been implemented and the release branch is ready, a [Pull Request (PR)](./pull_request.md) can be started to merge it into `main`.
+
+:::{warning}
+A [Pull Request (PR)](./pull_request.md) **must** be performed to merge a `release` into `main`.
+:::
+
+```{mermaid}
+%%{init: { 'gitGraph': {'showCommitLabel': false}} }%%
+gitGraph
+   commit
+   commit tag: "v1.0.0"
+   branch release/v2.0.x
+   commit
+   commit
+   commit
+   checkout main
+   merge release/v2.0.x tag: "v2.0.0"
+```
+
+In an ideal world, the work on release v3.0.0 can begin after release v2.0.0 is completed and the new tag can be used as a branching point for the next release branch. In practice, shifting priorities and complexities will result in the need for parallel release branches as shown below.
+
+```{mermaid}
+%%{init: { 'gitGraph': {'showCommitLabel': false}} }%%
+gitGraph
+   commit
+   commit tag: "v1.0.0"
+   branch release/v2.0.x
+   commit
+   commit
+   branch release/v3.0.x
+   commit
+   checkout release/v2.0.x
+   commit
+   checkout main
+   merge release/v2.0.x tag: "v2.0.0"
+   checkout release/v3.0.x
+   merge release/v2.0.x
+   commit
+   commit
+   checkout main
+   merge release/v3.0.x tag: "v3.0.0"
+```
+
+:::{important}
+Do not delete the `release/` branches after these have been merged to `main`!
+You can keep using them for future patches or bugfixes, or as reference for future development.
+:::
+
+## Feature branches
+
+Feature branches are created to implement or change a distinct feature. There are no special restrictions on feature branches and work can be directly commited to a feature branch.
+
+Feature branch naming convention is a prefix plus the name of the feature to be worked on, like `feature/multiuser_support` or `feature/client_rework`.
+
+```{mermaid}
+%%{init: { 'gitGraph': {'showCommitLabel': false}} }%%
+gitGraph
+   commit tag: "v1.0.0"
+   branch release/v2.0.x
+   branch feature/multiuser_support
+   commit
+   checkout release/v2.0.x
+   branch feature/client_rework
+   commit
+   checkout feature/multiuser_support
+   commit
+   checkout feature/client_rework
+   commit
+   checkout release/v2.0.x
+   merge feature/multiuser_support
+   merge feature/client_rework
+   checkout main
+   merge release/v2.0.x tag: "v2.0.0"
+```
+
+:::{warning}
+A [Pull Request (PR)](./pull_request.md) **must** be performed to merge a `feature` into a `release`.
+:::
+
+## Bugfix branches
+
+Bugfix branches are indicated by the `bugfix/<name>` naming sheme. They are used to solve identified issues in already existing releases.
+To make these fixes available for already published releases, a special release branch can be created. For example branch `release/v4.0.x` would serve as the way to release bugfix versions of release v4.0.0.
+This allows for a cleaner main branch and the possibility to resolve issues in old releases without affecting the work for future software versions.
+
+```{mermaid}
+%%{init: { 'gitGraph': {'showCommitLabel': false}} }%%
+gitGraph
+    commit tag: "v3.0.0"
+    branch release/v4.0.x
+    commit
+    checkout main
+    merge release/v4.0.x tag: "v4.0.0"
+    branch release/v5.0.x
+    commit
+    checkout main
+    checkout release/v4.0.x
+    branch bugfix/error_condition
+    commit
+    commit
+    checkout release/v4.0.x
+    merge bugfix/error_condition
+    checkout main
+    merge release/v4.0.x tag: "v4.0.1"
+    checkout release/v5.0.x
+    commit
+    checkout main
+    merge release/v5.0.x tag: "v5.0.0"
+```
+
+:::{warning}
+A [Pull Request (PR)](./pull_request.md) **must** be performed to merge a `bugfix` into a `release`.
+:::

doc/branches/pull_request.md

@@ -0,0 +1,21 @@
+# Pull Requests
+
+Some aspects of the Pull Request (PR) interface are highlighted on this page.
+
+## Introduction
+
+A Pull Request is a useful mechanism to integrate changes and new additions into the existing code. Instead of just merging changes made in a `feature` or `bugfix` branch into a `release` branch, the Pull Request allows the creator of the changes to present all of their work to their collaborators. They must review these changes before they are added to the more stable branches.
+
+You can find information on where Pull Requests are mandatory on the [branches page](./branch_types.md).
+
+## Anatomy of a Pull Request
+
+A Pull Request in GitHub looks like this:
+
+![image](./images/pr_overview.png)
+
+1. The status of the PR, the source and target branches are also shown. Below that, all the user actions are detailed chronologically. The "Files changed" tab allows for a detailed view of the changes, allowing reviewers and creator to exchange comments and requests.
+
+2. The creator of the pull request and all invited reviewers and their approval status are shown.
+
+3. On the bottom of the page, the proposed changes are automatically checked for potential conflicts using [Continous Integration](../ci/ci.md). If enough approved reviews are conducted and all tests are successful, a collaborator with write access to the target branch can merge the Pull Request.