V8.02.512.2025.05.30

Signed-off-by: Marc S. Weidner <msw@coresecret.dev>

docs/CODING_CONVENTION.md

@@ -0,0 +1,80 @@
+---
+gitea: none
+include_toc: true
+---
+
+# 1. CISS.debian.live.builder
+
+**Centurion Intelligence Consulting Agency Information Security Standard**<br>
+*Debian Live Build Generator for hardened live environment and CISS Debian Installer*<br>
+**Master Version**: 8.02<br>
+**Build**: V8.02.512.2025.05.30<br>
+
+# 2. Coding Style
+
+## 2.1. PR
+
+You'd make the life of the maintainers easier if you submit only _one_ patch with _one_ functional change per PR.
+
+## 2.2 Documentation
+
+Some people really read that ! New features would need to be documented in the appropriate section in `usage()` and in
+`~/docs/DOCUMENTATION.md`.
+
+## 2.3. Coding
+
+### 2.3.1. Shell / bash
+
+Bash is actually quite powerful—not only with respect to sockets. It's not as mighty as perl or python, but there are a lot of
+neat features. Here's how you make use of them. Besides those short hints here, there's a wealth of information there.
+
+* Don't use backticks anymore, use `$(..)` instead
+* Use double square `[[]]` brackets (_conditional expressions)_ instead of single square `[]` brackets
+* In double square brackets, avoid quoting at the right-hand side if not necessary. For regex matching (`=~`) you shouldn't
+  quote at all.
+* The [BashPitfalls](http://mywiki.wooledge.org/BashPitfalls) is a good read!
+* Whenever possible try to avoid `tr` `sed` `awk` and use bash internal functions instead, see
+  e.g., [bash shell parameter substitution](http://www.cyberciti.biz/tips/bash-shell-parameter-substitution-2.html). It is
+  slower as it forks, fopens and pipes back the result.
+* `read` often can replace `awk`: `IFS=, read -ra a b c <<< "$line_with_comma"`
+* Bash can also deal perfectly with regular expressions, see
+  e.g., [here](https://www.networkworld.com/article/2693361/unix-tip-using-bash-s-regular-expressions.html)
+  and [here](https://unix.stackexchange.com/questions/421460/bash-regex-and-https-regex101-com). You can as well have a look @
+  `is_ipv4addr()` or `is_ipv6addr()`.
+* If you still need to use any of `tr`, `sed` and `awk`: try to avoid a mix of several external binaries e.g., if you can
+  achieve the same with e.g. `awk`.
+* Be careful with very advanced bash features. Mac OS X is still using bash version
+  3 ([differences](http://tldp.org/LDP/abs/html/bashver4.html)).
+* Always use a return value for a function/method. 0 means all is fine.
+* Make use of [shellcheck](https://github.com/koalaman/shellcheck) if possible.
+* Follow the [shellformat](https://google.github.io/styleguide/shellguide.html) Shell-Style Guide.
+
+### 2.3.2. Shell specific
+
+* Security:
+  * Watch out for any input especially (but not only) supplied from the server. Input should never be trusted.
+  * Unless you're really sure where the values come from, variables need to be put in quotes.
+
+### 2.3.3. Variables
+
+* Use **"speaking variables"** but don't overdo it with the length.
+* No _camelCase_, please. We distinguish between lowercase and uppercase only.
+  * Global variables:
+    * use them only when really necessary,
+    * in CAPS,
+    * initialize them (`declare -g VAR=""`),
+    * use `declare -g` and use typing (variable types) if possible.
+  * Local variables:
+    * are lower case,
+    * declare them before usage (`declare`),
+    * initialize them (`declare VAR=""`).
+  * Preferred declaration and initialization:
+    * VAR: `declare -g VAR=""` and `declare -a ARRAY=()`.
+
+# 3. Misc
+
+* Test before doing a PR! Best if you check with two bad and two good examples, which should then work as expected.
+
+---
+**[no tracking | no logging | no advertising | no profiling | no bullshit](https://coresecret.eu/)**
+<!-- vim: set number et ts=2 sw=2 sts=2 ai tw=128 ft=markdown -->