---
gitea: none
include_toc: true
---

# Contributing

This is a personal project and I won't accept your pull-requests. You are
however welcome to fork and modify it while following the guidelines and
licenses in [COPYING.md](./COPYING.md).

## Coding conventions/formatting

There is a [.editorconfig](./.editorconfig) file to use with compatible editors
[1](https://editorconfig.org/#pre-installed), or with those who have plugins
available [2](https://editorconfig.org/#download).

In addition, we use the clang-formatter (configuration in
[.clang-format](./.clang-format))

Please use [prettier](https://prettier.io/) and the supplied
[configuration](./.prettierrc) to format the following file types:

- `.md`

Use the following formatters with the following types:

- `.cpp` and `.h` (use clang-format)

No formatter specified for the following types (adapt to existing style):

- `.ini`

Do **not** change the formatting of license texts (e.g.
[COPYING.md](./COPYING.md)).

### General

- We indent using `tabs` (4 spaces wide).
- We use single-quotes `'` where possible.
- We use `LF` line endings (enforced by [.gitattributes](./.gitattributes)).
- We use `UTF-8` encoding where possible.
- We end files with an empty line.
- We use the string `TODO` to mark bits of code that need improvement.
- We use the string `DEBUG` to mark bits of code that are only for debugging
  (remove before next commit).
- We use `YYYY-MM-DD hh:mm:ss` (in `UTC`) as date & time format.
- We use `camelCase` where possible.
- We add (if possible) the following header to files that contain a reasonable
  amount of self-written code or are essential to the project:

  ```text
  /*
  ESP8266-IOT-timer
  Copyright © YYYY name your@email

  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, version 3.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
  ```

### File specific rules

#### Markdown (.md)

- We add a single `h1` element per document (as a title of the document).
- We use asterisks `*` for **bold** and _italic_, not underscores `_`.
- We don't use citation blocks `>` for emphasis.
- We end sentences with a full stop `.`.
- We add new lines around codeblocks ` ``` `.
- We indent using spaces (2 spaces wide).
- We add a table of content (toc) in gitea's style where necessary:

  ```
  ---
  gitea: none
  include_toc: true
  ---
  ```

## Commit messages

- We write in all lowercase except for special names, e.g. `update Makefile`
- We write in imperative mood, e.g. `add contribution guidelines`, not
  `adding ... ` or `adds ... `.