From 35643aacfd27381eb627bddf121fa8594e81064c Mon Sep 17 00:00:00 2001
From: bikerdanny <62376119+bikerdanny@users.noreply.github.com>
Date: Mon, 26 Apr 2021 06:07:32 +0200
Subject: [PATCH] Added CONTRIBUTE.md and fixed Dockerfile

---
 Dockerfile                          |   4 +-
 doc.zih.tu-dresden.de/CONTRIBUTE.md | 102 ++++++++++++++++++++++++++++
 2 files changed, 104 insertions(+), 2 deletions(-)
 create mode 100644 doc.zih.tu-dresden.de/CONTRIBUTE.md

diff --git a/Dockerfile b/Dockerfile
index c5652dc4a..3985d90ca 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -7,8 +7,8 @@ RUN pip install mkdocs>=1.1.2
 # (https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)
 RUN pip install mkdocs-material>=5.4.0
 
-COPY doc.zih.tu-dresden.de/ /src/
-
 WORKDIR /src
+COPY doc.zih.tu-dresden.de/ /src/
 
 RUN mkdocs build
+
diff --git a/doc.zih.tu-dresden.de/CONTRIBUTE.md b/doc.zih.tu-dresden.de/CONTRIBUTE.md
new file mode 100644
index 000000000..f5d36f9a2
--- /dev/null
+++ b/doc.zih.tu-dresden.de/CONTRIBUTE.md
@@ -0,0 +1,102 @@
+# Contribution Guide
+
+In the following, it is outlined how to contribute to the HPC documentation of TU Dresden and which
+rules should be followed when adding to this project.
+
+## Setup
+todo
+
+## Git Workflow
+todo
+
+##
+
+
+## Content Rules
+
+### Markdown
+todo
+
+### Markdown Linter
+
+The (markdown linter client)[https://github.com/igorshubovych/markdownlint-cli] should be invoked to
+help keep the markdown source code clean and consistent.
+
+```shell
+npm install markdownlint-cli
+```
+
+```shell
+markdownlint docs/index.md
+docs/index.md:8:131 MD013/line-length Line length [Expected: 130; Actual: 138]
+```
+
+configuration file: `.markdownlint.json`
+
+Before commiting, invoke the script `util/lint-changes.sh` which calls the markdownlint tool for all
+(git-)changed markdown files
+
+```shell
+sh util/lint-changes.sh
+hpc-compendium-2.0-gitlab-tudzih git:(master) ✗ sh util/lint-changes.sh
+README.md:6 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]
+README.md:7 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 3]
+README.md:21 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]
+README.md:22 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "### Why is this not at gitlab.hrz.tu-chemnitz.de?"]
+[8< 8<]
+```
+
+## Check Links
+
+We can use `util/check-links.sh` or [markdown-link-check](https://github.com/tcort/markdown-link-check)
+
+```shell
+npm i -D markdown-link-check
+[8< 8<]
+./node_modules/markdown-link-check/markdown-link-check docs/index.md
+
+FILE: docs/index.md
+[✖] google.de
+
+1 links checked.
+
+ERROR: 1 dead links found!
+[✖] google.de → Status: 400
+```
+
+### Writing Style
+
+### Spelling and Technical Wording
+
+* Language settings: en_us
+* I/O not IO
+* Slurm not SLURM
+* Filesystem not file system
+
+### Command Prompts
+
+Showing commands and sample output is a important part of the documentation. Thus, some rules should
+be followed.
+
+1. Prompts: It should be clear from the prompt, where the command is run (e.g. Taurus, specific partition or local machine).
+
+   * Taurus / HPC systems of TUD in general: `taurus$`
+   * Specific kind of node or partition: `tauruslogin$`, `taurus-ml$` `taurus-rome$`etc.
+     * TODO: Remove prefix `taurus`?
+   * Local machine: `localhost$`
+
+1. Use generic user name, e.g. `zwulf`:
+```shell
+taurus$ ls -l
+drwxr-xr-x   3 zwulf p_zwulf      4096 Jan 24  2020 code
+drwxr-xr-x   3 zwulf p_zwulf      4096 Feb 12  2020 data
+-rw-rw----   1 zwulf p_zwulf      4096 Jan 24  2020 readme.md
+```
+
+1. Schere: If showing only a snippet of a long output, omissions are marked with
+  * `8< 8<`
+  * `[snip]`
+  * `[...]`
+  * TODO: Choose one.
+
+
-- 
GitLab