150 lines
4.3 KiB
Markdown
150 lines
4.3 KiB
Markdown
---
|
|
gitea: none
|
|
include_toc: true
|
|
---
|
|
|
|
# Contributing
|
|
|
|
This is a personal project to learn new languages and technics and thus does not
|
|
really have a future you could contribute to. You are however welcome to fork
|
|
and modify it while following the guidelines and licenses in
|
|
[COPYING.md](./COPYING.md).
|
|
|
|
## Environment
|
|
|
|
Preferred editor: [VSCodium](https://vscodium.com/) with some
|
|
[extensions](./.vscode/extensions.json).
|
|
|
|
For dependencies/tools, make sure to use the versions specified in
|
|
[INSTALL.md#requirements](./INSTALL.md#requirements).
|
|
|
|
## 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).
|
|
|
|
Please use [prettier](https://prettier.io/) and the supplied
|
|
[configuration](./.prettierrc) to format the following file types:
|
|
|
|
- `.js`
|
|
- `.vue`
|
|
- `.css`
|
|
- `.md`
|
|
- `.yaml`
|
|
- `.graphqls`, `.graphql`
|
|
- `.json`
|
|
|
|
Use the following formatters with the following types:
|
|
|
|
- `.go` (use gofmt)
|
|
|
|
No formatter specified for the following types (adapt to existing style):
|
|
|
|
- `Makefile`
|
|
- `.sql`
|
|
- `.mod`, `.sum`
|
|
|
|
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
|
|
/*
|
|
YetAnotherToDoList
|
|
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
|
|
|
|
#### SQL (.sql)
|
|
|
|
- We avoid using spaces and keywords (escape with `` ` `` if necessary).
|
|
- We write keywords in queries as `ALL CAPS`.
|
|
- We name databases in `ALL CAPS`
|
|
- We name tables in `PascalCase`.
|
|
- We name columns in `camelCase`.
|
|
- We name foreign keys in this scheme: `FK_SourceTable_sourceColumn`.
|
|
- We prefix booleans with `IS_`.
|
|
|
|
#### 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
|
|
---
|
|
```
|
|
|
|
#### YAML (.yaml)
|
|
|
|
We indent using spaces (1 space wide).
|
|
|
|
#### Bash (.sh)
|
|
|
|
We use `env` in the shebang: `#!/usr/bin/env bash`.
|
|
|
|
### File endings
|
|
|
|
#### .yaml and .yml
|
|
|
|
We use the `.yaml` file ending.
|
|
|
|
#### .graphql and .graphqls
|
|
|
|
- We use `.graphql` for writing client queries.
|
|
|
|
- We use `.graphqls` for defining our graph scheme.
|
|
|
|
## Generating code/using tools
|
|
|
|
This paragraph does not refer to code generation using neural networks/Ai/LLMs,
|
|
which is currently disallowed, but instead to _classical Codegen_ (e.g.
|
|
[gqlgen](https://github.com/99designs/gqlgen)).
|
|
|
|
- We document the general steps & commands we use to generate code in
|
|
[CMD_HISTORY.md](./CMD_HISTORY.md) and commit the result without much
|
|
modifications. Instead, we commit the necessary changes in an additional
|
|
commit.
|
|
|
|
## 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 ... `.
|