diff --git a/docs/content/contributing/coding-style.md b/docs/content/contributing/coding-style.md deleted file mode 100644 index 06a1d6ba..00000000 --- a/docs/content/contributing/coding-style.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: 'Contributing | Coding Style' ---- - -## Bash and Shell - -When refactoring, writing or altering scripts, that is Shell and bash scripts, in any way, adhere to these rules: - -1. **Adjust your style of coding to the style that is already present**! Even if you do not like it, this is due to consistency. There was a lot of work involved in making all scripts consistent. -2. **Use `shellcheck` to check your scripts**! Your contributions are checked by GitHub Actions too, so you will need to do this. You can **lint your work with `make lint`** to check against all targets. -3. **Use the provided `.editorconfig`** file. -4. Use `/bin/bash` instead of `/bin/sh`. Adjust the style accordingly. -5. `setup.sh` provides a good starting point to look for. -6. When appropriate, use the `set` builtin. We recommend `set -euEo pipefail` or `set -uE`. - -## Styling rules - -### If-Else-Statements - -```bash -# when using braces, use double braces -# remember you do not need "" when using [[ ]] -if [[ ]] && [[ -f ${FILE} ]] -then - -# when running commands, you don't need braces -elif - -else - -fi - -# equality checks with numbers are done -# with -eq/-ne/-lt/-ge, not != or == -if [[ ${VAR} -ne 42 ]] || [[ ${SOME_VAR} -eq 6 ]] -then - -fi -``` - -### Variables & Braces - -!!! attention - - Variables are always uppercase. We always use braces. - -If you forgot this and want to change it later, you can use [this link][regex]. 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 -> CI will fail -var="bad" -new=$var -``` - -### Loops - -Like `if-else`, loops look like this - -```bash -for / while -do - -done -``` - -### Functions - -It's always nice to see the use of functions as 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`. - -```bash -function _ -{ - - - # variables that can be local should be local - local -} -``` - -### Error Tracing - -A construct to trace error in your scripts looks like this. Remember: Remove `set -x` in the end. This is for debugging purposes only. - -```bash -set -xeuEo pipefail -trap '__err "${BASH_SOURCE}" "${FUNCNAME[0]:-?}" "${BASH_COMMAND:-?}" "${LINENO:-?}" "${?:-?}"' ERR - -function __err -{ - local RED="\e[31m\e[1m" - local RESET="\e[0m" - local ERR_MSG="\n--- ${RED}UNCHECKED ERROR${RESET}" - ERR_MSG+="\n - script = ${1}" - ERR_MSG+="\n - function = ${2}" - ERR_MSG+="\n - command = ${3}" - ERR_MSG+="\n - line = ${4}" - ERR_MSG+="\n - exit code = ${5}" - - echo -e "${ERR_MSG}" - - -} -``` - -### Comments, Descriptiveness & An Example - -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. - -A positive example, which is taken from `setup-stack.sh`, would be - -```bash -function _setup_postfix_aliases -{ - _log 'debug' 'Setting up Postfix aliases' - - : >/etc/postfix/virtual - : >/etc/postfix/regexp - - if [[ -f /tmp/docker-mailserver/postfix-virtual.cf ]] - then - # fixing old virtual user file - if grep -q ",$" /tmp/docker-mailserver/postfix-virtual.cf - then - sed -i -e "s/, /,/g" -e "s/,$//g" /tmp/docker-mailserver/postfix-virtual.cf - fi - - cp -f /tmp/docker-mailserver/postfix-virtual.cf /etc/postfix/virtual - - while read -r FROM _ - do - # Setting variables for better readability - UNAME=$(echo "${FROM}" | cut -d @ -f1) - DOMAIN=$(echo "${FROM}" | cut -d @ -f2) - - # if they are equal it means the line looks like: "user1 other@example.com" - [[ ${UNAME} != "${DOMAIN}" ]] && echo "${DOMAIN}" >>/tmp/vhost.tmp - done < <(grep -v "^\s*$\|^\s*\#" /tmp/docker-mailserver/postfix-virtual.cf || true) - else - _log 'debug' "'/tmp/docker-mailserver/postfix-virtual.cf' not provided - no mail alias/forward created" - fi - - ... -} -``` - -## YAML - -When formatting YAML files, use [Prettier][prettier], an opinionated formatter. There are many plugins for IDEs around. - -[semver]: https://semver.org/ -[regex]: https://regex101.com/r/ikzJpF/7 -[prettier]: https://prettier.io diff --git a/docs/content/contributing/documentation.md b/docs/content/contributing/documentation.md deleted file mode 100644 index 86bdb10f..00000000 --- a/docs/content/contributing/documentation.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: 'Contributing | Documentation' ---- - -## Prerequisites - -You will need have Python and Python pip installed. Or just docker. - -## Building and serving the documentation - -This tutorial was written using Python `2.7.18` and Python pip `20.3.4`. -And Docker `19.03.6`. - -### Python way - -#### Install the modules - -The documentation builder - -```sh -pip install mkdocs -``` - -Now the theme - -```sh -pip install mkdocs-material -``` - -#### Serve - -!!! note "Note: be sure to be in the docs folder (`cd ./docs/`)" - -```sh -mkdocs serve -``` - -Wait for it to build and open the URL in your browser. -Each change will be hot-reloaded onto the page you view, just edit, save and look at the result. - -### Docker way - -Using the official image ([squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material)) for our documentation theme. - -#### Serve - -!!! note "Note: be sure to be in the docs folder (`cd ./docs/`)" - -```sh -docker run --rm -it -p 8000:8000 -v "${PWD}:/docs" squidfunk/mkdocs-material -``` - -Each change will be hot-reloaded onto the page you view, just edit, save and look at the result. diff --git a/docs/content/contributing/general.md b/docs/content/contributing/general.md new file mode 100644 index 00000000..da3b00fc --- /dev/null +++ b/docs/content/contributing/general.md @@ -0,0 +1,37 @@ +--- +title: 'Contributing | General Information' +--- + +## Coding Style + +When refactoring, writing or altering scripts or other files, adhere to these rules: + +1. **Adjust your style of coding to the style that is already present**! Even if you do not like it, this is due to consistency. There was a lot of work involved in making all scripts consistent. +2. **Use `shellcheck` to check your scripts**! Your contributions are checked by GitHub Actions too, so you will need to do this. You can **lint your work with `make lint`** to check against all targets. +3. **Use the provided `.editorconfig`** file. +4. Use `/bin/bash` instead of `/bin/sh` in scripts + +## Tests + +To run the test suite, you will need to + +1. [Install Docker] +2. Install `jq` (under Ubuntu, use `sudo apt-get -y install jq`) +3. Execute `git submodule update --init --recursive` if you haven't already initialized the git submodules +4. Execute `make clean all` + +!!! info "Can I use MacOS?" + + We do not support running linting, tests, etc on macOS at this time. Please use a linux VM. + +[Install Docker]: https://docs.docker.com/get-docker/ + +## Documentation + +You will need to have Docker installed. Navigate into the `docs/` directory. Then run: + +```sh +docker run --rm -it -p 8000:8000 -v "${PWD}:/docs" squidfunk/mkdocs-material +``` + +This serves the documentation on your local machine on port `8000`. Each change will be hot-reloaded onto the page you view, just edit, save and look at the result. diff --git a/docs/content/contributing/issues-and-pull-requests.md b/docs/content/contributing/issues-and-pull-requests.md index 4a56faf6..3851ea9d 100644 --- a/docs/content/contributing/issues-and-pull-requests.md +++ b/docs/content/contributing/issues-and-pull-requests.md @@ -22,29 +22,26 @@ Maintainers take the time to improve on this project and help by solving issues ## Pull Requests -### Submit a Pull-Request - !!! question "Motivation" You want to add a feature? Feel free to start creating an issue explaining what you want to do and how you're thinking doing it. Other users may have the same need and collaboration may lead to better results. +### Submit a Pull-Request + The development workflow is the following: -1. Fork the project and clone your fork - 1. Create a new branch to work on - 2. Run `git submodule update --init --recursive` +1. Fork the project and clone your fork with `git clone --recurse-submodules ...` or run `git submodule update --init --recursive` after you cloned your fork 2. Write the code that is needed :D 3. Add integration tests if necessary -4. [Prepare your environment and run linting and tests][docs-tests] -5. Document your improvements if necessary (e.g. if you introduced new environment variables, describe those in the [ENV documentation][docs-environment]) -6. [Commit][commit] and [sign your commit][gpg], push and create a pull-request to merge into `master`. Please **use the pull-request template** to provide a minimum of contextual information and make sure to meet the requirements of the checklist. - 1. Pull requests are automatically tested against the CI and will be reviewed when tests pass - 2. When your changes are validated, your branch is merged - 3. CI builds the new `:edge` image immediately and your changes will be includes in the next version release. +4. [Prepare your environment and run linting and tests][docs-general-tests] +5. Document your improvements if necessary (e.g. if you introduced new environment variables, describe those in the [ENV documentation][docs-environment]) and add your changes the changelog under the "Unreleased" section +6. [Commit][commit] (and [sign your commit][gpg]), push and create a pull-request to merge into `master`. Please **use the pull-request template** to provide a minimum of contextual information and make sure to meet the requirements of the checklist. + +Pull requests are automatically tested against the CI and will be reviewed when tests pass. When your changes are validated, your branch is merged. CI builds the new `:edge` image immediately and your changes will be includes in the next version release. [docs]: https://docker-mailserver.github.io/docker-mailserver/edge [github-file-readme]: https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md [docs-environment]: ../config/environment.md -[docs-tests]: ./tests.md +[docs-general-tests]: ./general.md#tests [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 diff --git a/docs/content/contributing/tests.md b/docs/content/contributing/tests.md deleted file mode 100644 index 4192a6fd..00000000 --- a/docs/content/contributing/tests.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: 'Contributing | Tests' ---- - -1. Install docker -2. Execute `git submodule update --init --recursive` -3. Install jq -4. Execute `make clean all` - - -!!! info "Can I use MacOS?" - - We do not support running linting, tests, etc on macOS at this time. Please use a linux VM. \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index bfd355d5..5f5df364 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -160,9 +160,7 @@ nav: - 'Customize IMAP Folders': examples/use-cases/imap-folders.md - 'FAQ' : faq.md - 'Contributing': + - 'General Information': contributing/general.md - 'Issues and Pull Requests': contributing/issues-and-pull-requests.md - - 'Coding Style': contributing/coding-style.md - - 'Tests': contributing/tests.md - - 'Documentation': contributing/documentation.md - 'DockerHub': https://hub.docker.com/r/mailserver/docker-mailserver/ - 'GHCR': https://github.com/docker-mailserver/docker-mailserver/pkgs/container/docker-mailserver