mirror of
https://github.com/docker-mailserver/docker-mailserver.git
synced 2024-01-19 02:48:50 +00:00
CONTRIBUTING.md "moved" to documentation (#2081)
This commit is contained in:
Casper
GitHub
parent
360a8f718e
commit
6becd9e153
195
CONTRIBUTING.md
195
CONTRIBUTING.md
|
|
@ -1,195 +0,0 @@
|
|||
# Contributing
|
||||
|
||||
This project is Open Source. That means that you can contribute on enhancements, bug fixing or improving the [documentation](https://docker-mailserver.github.io/docker-mailserver/edge).
|
||||
|
||||
1. [Issues & PRs](#issues--prs)
|
||||
1. [Opening an Issue](#opening-an-issue)
|
||||
2. [Pull Request](#pull-requests)
|
||||
2. [Coding Style](#coding-style)
|
||||
1. [Bash and Shell](#bash-and-shell)
|
||||
2. [YAML](#yaml)
|
||||
|
||||
## Issues & PRs
|
||||
|
||||
### Opening an Issue
|
||||
|
||||
**Before opening an issue**, read the [`README`](./README.md) carefully, use the [Documentation](https://docker-mailserver.github.io/docker-mailserver/edge), the Postfix/Dovecot documentation and your search engine you trust. The issue tracker is not meant to be used for unrelated questions! When opening an issue, please provide details use case to let the community reproduce your problem. Please start the mail server with env `DMS_DEBUG=1` and paste the output into the issue. **Use the issue templates** to provide the necessary information. Issues which do not use these templates are not worked on and closed. By raising issues, I agree to these terms and I understand, that the rules set for the issue tracker will help both maintainers as well as everyone to find a solution.
|
||||
|
||||
Maintainers take the time to improve on this project and help by solving issues together. It is therefore expected from others to make an effort and **comply with the rules**.
|
||||
|
||||
### Pull Requests
|
||||
|
||||
#### Submit a Pull-Request
|
||||
|
||||
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.
|
||||
|
||||
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`
|
||||
2. Write the code that is needed :D
|
||||
3. Add integration tests if necessary
|
||||
4. Get the linters with `make install_linters` and install `jq` with the package manager of your OS
|
||||
5. Use `make clean all` to build image locally and run tests (note that tests work on Linux **only**)
|
||||
6. Document your improvements if necessary (e.g. if you introduced new environment variables, describe those in the [ENV documentation](./docs/content/config/environment.md))
|
||||
7. [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.
|
||||
|
||||
## 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 TravisCI 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` or `/usr/bin/env 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
|
||||
|
||||
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 -> TravisCI 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 '__log_err ${FUNCNAME[0]:-"?"} ${BASH_COMMAND:-"?"} ${LINENO:-"?"} ${?:-"?"}' ERR
|
||||
|
||||
SCRIPT='name_of_this_script.sh'
|
||||
|
||||
function __log_err
|
||||
{
|
||||
printf "\n--- \e[1m\e[31mUNCHECKED ERROR\e[0m\n%s\n%s\n%s\n%s\n\n" \
|
||||
" - script = ${SCRIPT:-${0}}" \
|
||||
" - function = ${1} / ${2}" \
|
||||
" - line = ${3}" \
|
||||
" - exit code = ${4}" 1>&2
|
||||
|
||||
<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 `start-mailserver.sh`, would be
|
||||
|
||||
``` BASH
|
||||
function _setup_postfix_aliases
|
||||
{
|
||||
_notify 'task' '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
|
||||
|
||||
# the `to` is important, don't delete it
|
||||
# shellcheck disable=SC2034
|
||||
while read -r FROM TO
|
||||
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@domain.tld"
|
||||
[[ "${UNAME}" != "${DOMAIN}" ]] && echo "${DOMAIN}" >> /tmp/vhost.tmp
|
||||
done < <(grep -v "^\s*$\|^\s*\#" /tmp/docker-mailserver/postfix-virtual.cf || true)
|
||||
else
|
||||
_notify 'inf' "Warning 'config/postfix-virtual.cf' is 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.
|
||||
|
||||
[//]: # (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/7
|
||||
[prettier]: https://prettier.io
|
||||
|
|
@ -14,7 +14,7 @@ A fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.)
|
|||
If you have issues, read the full `README` **and** the [documentation][documentation::web] **for your version** (default is `edge`) first **before opening an issue**. The issue tracker is for issues, not for personal support.
|
||||
|
||||
1. [Included Services](#included-services)
|
||||
2. [Issues and Contributing](./CONTRIBUTING.md)
|
||||
2. [Issues and Contributing](https://docker-mailserver.github.io/docker-mailserver/edge/contributing/issues-and-pull-requests/)
|
||||
3. [Requirements](#requirements)
|
||||
4. [Usage](#usage)
|
||||
5. [Examples](#examples)
|
||||
|
|
|
|||
Loading…
Reference in a new issue