YetAnotherToDoList/CONTRIBUTING.md

Table of Contents

• Contributing
• Environment
• Coding conventions/formatting
• General
• File specific rules
• SQL (.sql)
• Markdown (.md)
• YAML (.yaml)
• Bash (.sh)
• File endings
• .yaml and .yml
• .graphql and .graphqls
• Generating code/using tools
• Commit messages

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.

Environment

Preferred editor: VSCodium with some extensions.

For dependencies/tools, make sure to use the versions specified in INSTALL.md#requirements.

Coding conventions/formatting

There is a .editorconfig file to use with compatible editors 1, or with those who have plugins available 2.

Please use prettier and the supplied configuration 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).

General

• We indent using tabs (4 spaces wide).

• We use single-quotes ' where possible.

• We use LF line endings (enforced by .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:

  /*
  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).

• We document the general steps & commands we use to generate code in 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 ... .