diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
deleted file mode 100644
index f1875b3481da6d11053e5ad8aed49ae53033e5c4..0000000000000000000000000000000000000000
--- a/.gitlab-ci.yml
+++ /dev/null
@@ -1,87 +0,0 @@
-variables:
- GIT_STRATEGY: none
- DOCKER_IMAGE: webpage:$CI_PIPELINE_ID
-
-workflow:
- rules:
- - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
- when: never
- - if: '$CI_COMMIT_BRANCH'
-
-stages:
- - build
- - test
- - release
- - cleanup
-
-
-Build Linter:
- stage: build
- variables:
- GIT_STRATEGY: clone
- GIT_DEPTH: 0
- script: docker build -t "${DOCKER_IMAGE}" .
-
-Test mkdocs:
- stage: test
- script: docker run ${DOCKER_IMAGE}
-
-Check wording of changed md-files:
- stage: test
- script:
- - docker run --rm -w /src -e CI_MERGE_REQUEST_TARGET_BRANCH_NAME "${DOCKER_IMAGE}"
- doc.zih.tu-dresden.de/util/grep-forbidden-words.sh
- only: [ merge_requests ]
-
-Lint changed md-files:
- stage: test
- script:
- - docker run --rm -w /src -e CI_MERGE_REQUEST_TARGET_BRANCH_NAME "${DOCKER_IMAGE}"
- doc.zih.tu-dresden.de/util/lint-changes.sh
- only: [ merge_requests ]
-
-Check spelling for changed md-files:
- stage: test
- script:
- - docker run --rm -w /src -e CI_MERGE_REQUEST_TARGET_BRANCH_NAME "${DOCKER_IMAGE}"
- doc.zih.tu-dresden.de/util/check-spelling.sh
- only: [ merge_requests ]
-
-Check links for changed md-files:
- stage: test
- script:
- - docker run --rm -w /src -e CI_MERGE_REQUEST_TARGET_BRANCH_NAME "${DOCKER_IMAGE}"
- doc.zih.tu-dresden.de/util/check-links.sh
- only: [ merge_requests ]
-
-Lint md-files:
- stage: test
- script: docker run --rm "${DOCKER_IMAGE}" markdownlint docs
- only: [ main, preview ]
-
-Check links for md-files:
- stage: test
- script:
- - docker run --rm "${DOCKER_IMAGE}"
- bash -c "find docs -type f -name '*.md' | xargs -L1 markdown-link-check --quiet"
- only: [ main, preview ]
-
-Release preview branch:
- stage: release
- script:
- - docker run --rm -v /var/www/html/preview:/mnt "${DOCKER_IMAGE}" mkdocs build --strict --site-dir /mnt
- only: [ preview ]
-
-Release:
- stage: release
- script:
- - docker run --rm -v /var/www/html/hpc-wiki:/mnt "${DOCKER_IMAGE}" mkdocs build --strict --site-dir /mnt
- only: [ main ]
-
-Cleanup docker:
- stage: cleanup
- script:
- - docker rmi -f "${DOCKER_IMAGE}"
- - docker system prune --force
- when: always
diff --git a/doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md b/doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md
index 3d3082e8969d486934449020fd7118f37a036e5d..ddb3951515d36a8344cd604f960560ed2c5e404d 100644
--- a/doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md
+++ b/doc.zih.tu-dresden.de/docs/contrib/howto_contribute.md
@@ -4,15 +4,86 @@
Ink is better than the best memory.
-This documentation is written in markdown and translated into static html pages using
-[mkdocs](https://www.mkdocs.org/). A single configuration file holds the pages structure
-as well as specification of the theme and extensions. This file is `mkdocs.yaml`.
+In this section you will find information on the technical setup of this documentation, the applied
+content rules, Git workflow and certain ways for contribution.
+
+Your contributions are highly welcome. This can range from adding new content, fixing typos,
+improving the phrasing and wording, adopting examples and command lines, etc. Our goal is to
+provide a consistent and up to date documentation. Thus, it is by no means a static documentation.
+Moreover, is is constantly reviewed and updated.
-We manage all essential files (markdown pages, graphics, configuration, theme, etc.) within a Git
-repository, which makes it quite easy to contribute to this documentation. In principle, there are
-three possible ways how to contribute to this documentation. These ways are outlined below.
+## Technical Setup
-## Content Guide Lines
+This documentation is written in markdown and translated into static html pages using
+[mkdocs](https://www.mkdocs.org/). The single configuration file `mkdocs.yml` holds the pages
+structure as well as specification of the theme and extensions.
+
+We manage all essential files (markdown pages, graphics, configuration, theme, etc.) within a
+[public Git repository](https://gitlab.hrz.tu-chemnitz.de/zih/hpcsupport/hpc-compendium), which
+makes it quite easy to contribute to this documentation. In principle, there are three possible ways
+how to contribute to this documentation. These ways are outlined below.
+
+!!! tip "Before you start"
+
+ Before you start your very first commit, please make sure, that you are familiar with our
+ [Git workflow](#git-workflow) and that you have at least skimmed the
+ [Content Guide Lines](content_rules.md).
+
+## Git Workflow
+
+We employ a so-called Git feature workflow with development branch. In our case, the working branch
+is called `preview` and is kept in parallel to the `main` branch.
+
+All contributions, e.g., new content, improved wording, fixed typos, etc, are added to separate
+feature branches which base on `preview`. If the contribution is ready, you will have to create a
+merge request back to the `preview` branch. A member of ZIH team will review the changes (four-eyes
+principle) and finally merge your changes to `preview`. All contributions need to pass the CI
+pipeline consisting of several checks to comply the content rules. Please, don't worry to much about
+this checks. ZIH staff will help you with that. You will find more information on the
+[CI/CD pipeline](cicd-pipeline) in the eponymous subsection.
+
+The changes on `preview` branch are either automatically merged into the `main` branch on every
+Monday via a pipeline schedule, or manually by admin staff. Moreover, the `main` branch is deployed
+to [https://compendium.hpc.tu-dresden.de](https://compendium.hpc.tu-dresden.de) and always reflects
+a production-ready state. Manual interventions are only necessary in case of merge conflicts. The
+admin staff will take care on this process.
+
+???+ note "Graphic on Git workflow"
+
+ The applied Git workflow is depicted in the following graphic. Here, two feature branches `foo`
+ and `bar` are created basing on `preview`. Three individual commits are added to branch `foo`
+ before it is ready and merged back to `preview`. The contributions on `bar` consist only one
+ commit. In the end, all contribution are merged to the `main` branch.
+
+ ```mermaid
+ %% Issues:
+ %% - showCommitLabel: false does not work; workaround is to use `commit id: " "`%%
+ %% - Changing the theme does not effect the rendered output. %%
+ %%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel': false} }%%
+ gitGraph
+ commit
+ branch preview
+ checkout preview
+ commit
+ branch foo
+ checkout foo
+ commit
+ commit
+ checkout preview
+ branch bar
+ checkout bar
+ commit
+ checkout preview
+ merge bar
+ checkout foo
+ commit
+ checkout preview
+ merge foo
+ checkout main
+ merge preview
+ ```
+
+## Content Rules
To ensure a high-quality and consistent documentation and to make it easier for readers to
understand all content, we set some [Content rules](content_rules.md). Please follow
@@ -46,8 +117,8 @@ documentation.
If you have a web browser (most probably you are using it to read this page) and want to contribute
to the documentation, you are good to go. GitLab offers a rich and versatile web interface to work
-with repositories. To start fixing typos and edit source files, please find more information on
-[Contributing via web browser](contribute_browser.md).
+with repositories. To start fixing typos and edit source files, please find more information on the
+page [Contributing via web browser](contribute_browser.md).
## Contribute via Local Clone
@@ -56,3 +127,16 @@ used in the back-end. Using them should ensure that merge requests will not be b
due to automatic checking.
The page on [Contributing via local clone](contribute_container.md) provides you with the details
about how to setup and use your local clone of the repository.
+
+
+
+## CI/CD Pipeline
+
+All contributions need to pass the CI pipeline which consists of various checks to ensure, that the
+[contentent rules](content_rules.md) are meet.
+
+The stages of the CI/CD pipeline are defined in a `.gitlab.yaml` file. For security reasons, this
+file is managed in a second, private repository.
+
+
+