github-com-docker-mailserver/docker-mailserver
1
0
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver.git synced 2024-01-19 02:48:50 +00:00
Code Issues Projects Releases Wiki Activity

update contributing documentation (#2789)

Browse source
This commit is contained in:
Georg Lauterbach 2022-09-23 08:23:20 +02:00 committed by GitHub
parent d6c7c2b3bc
commit fe2197ff7c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 47 additions and 237 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

156
docs/content/contributing/coding-style.md
View file

@ -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 [[ <CONDITION1> ]] && [[ -f ${FILE} ]]
then
<CODE TO RUN>
# when running commands, you don't need braces
elif <COMMAND TO RUN>
<CODE TO TUN>
else
<CODE TO TUN>
fi
# equality checks with numbers are done
# with -eq/-ne/-lt/-ge, not != or ==
if [[ ${VAR} -ne 42 ]] || [[ ${SOME_VAR} -eq 6 ]]
then
<CODE TO RUN>
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 <LOOP CONDITION>
do
<CODE TO RUN>
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 _<name_underscored_and_lowercase>
{
<CODE TO RUN>
# variables that can be local should be local
local <LOCAL_VARIABLE_NAME>
}
```
### 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}"
<CODE TO RUN AFTERWARDS>
}
```
### 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

53
docs/content/contributing/documentation.md
View file

@ -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.

37
docs/content/contributing/general.md Normal file
View file

@ -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.

21
docs/content/contributing/issues-and-pull-requests.md
View file

@ -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

13
docs/content/contributing/tests.md
View file

@ -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.

4
docs/mkdocs.yml
View file

@ -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