adjusted coding style guidelines; added table of contents

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## 6.2.0+
 
-see https://github.com/tomav/docker-mailserver/releases
+* see <https://github.com/tomav/docker-mailserver/releases>
 
 ## 6.1.0
 
@@ -56,93 +56,114 @@ see https://github.com/tomav/docker-mailserver/releases
   Fixes to setup where made for deletion and addition.
 
 ## 5.7.0
+
 * Delmailuser (#878)
   You can now delete users and the mailbox
 * Backup config folder while testing (#901)
 * added error messages to letsencrypt on startup (#898)
 
 ## 5.6.1
+
 * Update docker-configomat (#680)
 
 ## 5.6.0
+
 * Generate SRS secret on first run and store it (#891)
   The secret will be constant afther this.
 
 ## 5.5.0
+
 * Add /var/lib/dovecot to mailstate persistence (#887)
 
 ## 5.4.0
+
 * Allow configuring SRS secrets using the environment (#885)
   You can set your own secret with the env SRS_SECRET
   By default it uses the docker generated secret
 * Removed unneeded check for Let's encrypt cert.pem (#843)
 
 ## 5.3.0
+
 * Added reject_authenticated_sender_login_mismatch (#872)
   You can enable it with the env SPOOF_PROTECTION
   It is not enabled by default
 
 ## 5.2.0
+
 * Setting quiet mode on invoke-rc.d (#792)
 * Implement undef option for SA_SPAM_SUBJECT (#767)
 
 ## 5.1.0
+
 * Dkim key size can be changed (#868)
   It defaults to 2048 bits
 
 ## 5.0.1
+
 * update postmaster_address in dovecot config according to
   POSTMASTER_ADDRESS env var (#866)
 
 ## 5.0.0
+
 * Use Nist tls recommendations (#831)
   This might break access with older email clients that use
   an older version of openssl. You can TLS_LEVEL to lower
   the ciphers.
 
 ## 4.2.0
-*  Add environment variable to allow for customizing postsrsd's
+
-   SRS_EXCLUDE_DOMAINS setting (#849, #842)
+* Add environment variable to allow for customizing postsrsd's SRS_EXCLUDE_DOMAINS setting (#849, #842)
 
 ## 4.1.0
+
 * fixed greedy postgrey sed command (#845)
 * postscreen implementation altered (#846)
   You can now apply sender and receives restrictions
 
 ## 4.0.0
+
 * moved fail2ban function from setup.sh to own file (#837)
   This might break automatic scripting and you need to use
   fail2ban now
 
 ## 3.4.0
+
 * Generate new DH param weekly instead of daily (#834, #836)
 
 ## 3.3.1
+
 * added config-path option to setup.sh script (#698)
 
 ## 3.3.0
+
 * Restrict access (#452, #816)
 
 ## 3.2.3
+
 * Introduce .env for docker-compose examples (#815)
 
 ## 3.2.2
+
 * Changed Junk folder to be created and subscribed by default (#806)
 
 ## 3.2.1 (2018-02-06)
+
 * Added  reject_sender_login_mismatch (#811)
 
 ## 3.2.0 (2018-02-06)
+
 * Add SRS to fix SPF issues on redirect (#611, #814)
 
 ## 3.1.0 (2018-02-04)
+
 * Introduced Postscreen
   Breaks email submission on port 25. Sending emails should be done on port 465 or 587
 
 ## 3.0.0 (2018-02-04)
+
 * Image rebased on Debian stable
 
 ## 2.0.0 (2016-05-09)
+
 * New version
 * Major redesign of configuration
-

CONTRIBUTING.md

@@ -2,6 +2,13 @@
 
 `docker-mailserver` is OpenSource. That means that you can contribute on enhancements, bug fixing or improving the documentation in the Wiki.
 
+1. [Issues & PRs](#issues--prs)
+   1. [Open an Issue](#open-an-issue)
+   2. [Pull Request](#pull-requests)
+2. [Coding Style](#coding-style)
+   1. [Bash and Shell](#bash-and-shell)
+   2. [YAML](#yaml)
+
 ## Issues & PRs
 
 ### Open an issue
@@ -33,7 +40,7 @@ The development workflow is the following:
 - Use `make clean all` to build image locally and run tests
   Note that tests work on Linux only; they hang on Mac and Windows.
 - Document your improvements in `README.md` or Wiki depending on content
-- [Commit](https://help.github.com/articles/closing-issues-via-commit-messages/), push and make a pull-request
+- [Commit][commit], if possible with [signing your commit with a GPG key][gpg], push and make a pull-request
 - Pull-request is automatically tested on Travis
 - When tests are green, a review may be done
 - When changed are validated, your branch is merged into `master`
@@ -55,9 +62,9 @@ When refactoring, writing or altering Script, that is Shell and Bash scripts, in
 
 #### Styling rules
 
-##### initial description
+##### Initial Description
 
-When writing a script, provide the version and the script's task like so:
+When writing a script, provide the version and the script's task. We use [semantic versioning][semver] - so do you.
 
 ``` BASH
 #!/usr/bin/env bash
@@ -66,68 +73,46 @@ When writing a script, provide the version and the script's task like so:
 #
 # <TASK DESCRIPTION> -> cut this off
 # to make it not longer than approx.
-# 60 cols.
+# 80 cols.
 ```
 
-We use [semantic versioning](https://semver.org/) - so do you.
+##### If-Else-Statements
-
-##### if-else-statements
 
 ``` BASH
-if <CONDITION1>
+# when using braces, use double braces
+# remember you do not need "" when using [[ ]]
+if [[ <CONDITION1> ]] && [[ -f ${FILE} ]]
 then
   <CODE TO RUN>
-elif <CONDITION2>
+# when running code, you don't need them
+elif <COMMAND TO RUN>
   <CODE TO TUN>
 else
-  <CODE TO RUN>
+  <CODE TO TUN>
 fi
 
-# when using braces, use double braces!
+# equality checks with numbers, use
-if [[ <CONDITION1> ]] && [[ <CONDITION2> ]]
+# -eq/-ne/-lt/-ge, not != or ==
-then
+if [[ $VAR -ne 42 ]] || [[ $SOME_VAR -eq 6 ]]
-  <CODE TO RUN>
-fi
-
-# remember you do not need "" when using [[ ]]
-if [[ -f $FILE ]] # is fine
-then
-  <CODE TO RUN>
-fi
-
-# equality checks with numbers - use -eq/-ne/-lt/-ge, not != or ==
-if [[ $VAR -ne <NUMBER> ]] && [[ $SOME_VAR -eq 6 ]] || [[ $SOME_VAR -lt 42 ]]
-then
-  <CODE TO RUN>
-elif [[ $SOME_VAR -ge 242 ]]
 then
   <CODE TO RUN>
 fi
 ```
 
-##### variables
+##### Variables & Braces
 
-Variables are always uppercase.
+Variables are always uppercase. We always use braces. If you forgot this and want to change it later, you can use [this link][regex], which points to <https://regex101.com>. The used regex is `\$([^{("\\'\/])([a-zA-Z0-9_]*)([^}\/ \t'"\n.\]:]*)`, where you should in practice be able to replace all variable occurrences without braces with occurrences with braces.
 
 ``` BASH
 # good
 local VAR="good"
+local NEW="${VAR}"
 
 # bad
 var="bad"
 ```
 
-##### braces
+##### Loops
-
-We always use braces.
-
-``` BASH
-${VAR}
-```
-
-If you forgot this and want to change it later, you can use [this link](https://regex101.com/r/ikzJpF/4), which points to <https://regex101.com>. The used regex is `\$([^{("\\'\/])([a-zA-Z0-9_]*)([^}\/ \t'"\n.\]:]*)`, where you should in practice be able to replace all variable occurrences without braces with occurrences with braces.
-
-##### loops
 
 Like `if-else`, loops look like this
 
@@ -138,7 +123,7 @@ do
 done
 ```
 
-##### functions
+##### Functions
 
 It's always nice to see the use of functions. Not only as it's more C-style, but it also provides a clear structure. If scripts are small, this is unnecessary, but if they become larger, please consider using functions. When doing so, provide `function _main()`. When using functions, they are **always** at the top of the script!
 
@@ -152,9 +137,9 @@ function _<name_underscored_and_lowercase>()
 }
 ```
 
-##### error tracing
+##### Error Tracing
 
-A construct to trace error in your scripts looks like this:
+A construct to trace error in your scripts looks like this. Please use it like this (copy-paste) to make errors streamlined. Remember: Remove `set -x` in the end. This of debugging purposes only.
 
 ``` BASH
 set -euxEo pipefail
@@ -168,17 +153,14 @@ function _report_err()
 }
 ```
 
-Please use it like this (copy-paste) to make errors streamlined. Remember: Remove `set -x` in the end. This of debugging purposes only.
+##### Comments and Descriptiveness
 
-##### comments and descriptiveness
+Comments should only describe non-obvious matters. Comments should start lowercase when they aren't sentences. Make the code **self-descriptive** by using meaningful names! Make comments not longer than approximately 80 columns, then wrap the line.
-
-Comments should be kept minimal and only describe non-obvious matters, i.e. not what the code does. Comments should start lowercase as most of them are not sentences. Make the code **self-descriptive** by using meaningful names! Make comments not longer than approximately 60 columns, then wrap the line.
 
 A negative example:
 
 ``` BASH
-# adds one to the first argument
+# adds one to the first argument and print it to stdout
-# and print it to stdout
 function _add_one()
 {
   # save the first variable
@@ -200,3 +182,16 @@ function _add_one()
 {
   echo $(( $1 + 1 ))
 }
+```
+
+### YAML
+
+When formatting YAML files, you can opt for [Prettier][prettier]. There are any plugins for IDEs around.
+
+[//]: # (Links)
+
+[commit]: https://help.github.com/articles/closing-issues-via-commit-messages/
+[gpg]: https://docs.github.com/en/github/authenticating-to-github/generating-a-new-gpg-key
+[semver]: https://semver.org/
+[regex]: https://regex101.com/r/ikzJpF/4
+[prettier]: https://prettier.io

README.md

@@ -19,7 +19,15 @@ A fullstack but simple mail server (smtp, imap, antispam, antivirus...).
 Only configuration files, no SQL database. Keep it simple and versioned.
 Easy to deploy and upgrade.
 
-Why I created this image: [Simple mail server with Docker](http://tvi.al/simple-mail-server-with-docker/)
+Why I created this image: [Simple Mail Server with Docker](http://tvi.al/simple-mail-server-with-docker/)
+
+1. [Announcement](#announcement)
+2. [Includes](#includes)
+3. [Issues & Contributing](#issues--contributing)
+4. [Requirements](#requirements)
+5. [Usage](#usage)
+6. [Examples](#examples)
+7. [Environment Variables](#environment-variables)
 
 ## Announcement
 
@@ -161,12 +169,12 @@ If you got any problems with SPF and/or forwarding mails, give [SRS](https://git
 
 See the [wiki](https://github.com/tomav/docker-mailserver/wiki) for further details and best practice advice, especially regarding security concerns.
 
-### Examples
+## Examples
 
-#### Just the relevant environmental variables
+### With Relevant Environmental Variables
 
-```yaml
+``` YAML
-version: '2'
+version: '3.8'
 
 services:
   mail:
@@ -208,7 +216,7 @@ volumes:
 #### LDAP setup
 
 ``` YAML
-version: '2'
+version: '3.8'
 
 services:
   mail:
@@ -269,9 +277,7 @@ volumes:
 
 ## Environment variables
 
-Please check [how the container starts](https://github.com/tomav/docker-mailserver/blob/master/target/start-mailserver.sh) to understand what's expected. Also if an option doesn't work as documented here, check if you are running the latest image!
+If an option doesn't work as documented here, check if you are running the latest image! Value in **bold** is the default value.
-
-Value in **bold** is the default value.
 
 ### Assignments
 

target/helper_functions.sh

@@ -103,7 +103,7 @@ export -f _extract_certs_from_acme
 
 
 declare -A DEFAULT_VARS
-DEFAULT_VARS["DMS_DEBUG"]="${DMS_DEBUG:="0"}"
+DEFAULT_VARS["DMS_DEBUG"]="${DMS_DEBUG:=0}"
 
 function _notify()
 {
@@ -122,13 +122,13 @@ function _notify()
   case "${notification_type}" in
     'taskgrp' ) msg="${c_bold}${notification_msg}${c_reset}" ;;
     'task'    )
-      if [[ ${DEFAULT_VARS["DMS_DEBUG"]} == 1 ]]
+      if [[ ${DEFAULT_VARS["DMS_DEBUG"]} -eq 1 ]]
       then
         msg="  ${notification_msg}${c_reset}"
       fi
       ;;
     'inf'     )
-      if [[ ${DEFAULT_VARS["DMS_DEBUG"]} == 1 ]]
+      if [[ ${DEFAULT_VARS["DMS_DEBUG"]} -eq 1 ]]
       then
         msg="${c_green}  * ${notification_msg}${c_reset}"
       fi