mirror of
https://github.com/0rangebananaspy/authelia.git
synced 2024-09-14 22:47:21 +07:00
3695aa8140
This is a massive overhaul to the SQL Storage for Authelia. It facilitates a whole heap of utility commands to help manage the database, primary keys, ensures all database requests use a context for cancellations, and paves the way for a few other PR's which improve the database. Fixes #1337
135 lines
5.0 KiB
Markdown
135 lines
5.0 KiB
Markdown
---
|
|
layout: default
|
|
title: Style Guide
|
|
parent: Contributing
|
|
nav_order: 4
|
|
---
|
|
|
|
# Style Guide
|
|
|
|
This is a general guide to the code style we aim to abide by. This is by no means an exhaustive list and we're
|
|
constantly changing and improving it. This is also a work in progress document.
|
|
|
|
For our commit messages please see our [Commit Message Guidelines](./commitmsg-guidelines.md).
|
|
|
|
## Tools
|
|
|
|
We implement the following tools that help us abide by our style guide and include the configuration for them inside
|
|
our repository:
|
|
- [golangci-lint](https://github.com/golangci/golangci-lint)
|
|
- [yamllint](https://yamllint.readthedocs.io/en/stable/)
|
|
- [eslint](https://eslint.org/)
|
|
- [prettier](https://prettier.io/)
|
|
|
|
## Exceptions
|
|
|
|
This is a style **guide** not a cudgel, there are always going to be exceptions to these guidelines when it makes sense
|
|
not to follow them. One notable exception is the README.md for the repository. The line length of the
|
|
[All Contributors](https://allcontributors.org/) individual sections are longer than 120 characters and it doesn't make
|
|
sense to apply the [line length](#line-length) guidelines.
|
|
|
|
## Specific Guidelines
|
|
|
|
### Line Length
|
|
|
|
We aim to keep all files to a maximum line length of 120 characters. This allows for most modern computer systems to
|
|
display two files side by side (vertically split). As always, keep in mind you should not restrict your line length
|
|
when it doesn't make sense to.
|
|
|
|
This includes but is not limited to the following file types:
|
|
- Go (*.go)
|
|
- YAML (*.yml, *.yaml)
|
|
- Markdown (*.md)
|
|
- JavaScript (*.js)
|
|
- TypeScript (*.ts, *.tsx)
|
|
|
|
### Error Strings
|
|
|
|
Error messages should follow the standard go format. This format can be found in the [golang code review comments](https://github.com/golang/go/wiki/CodeReviewComments#error-strings)
|
|
however the key points are:
|
|
|
|
- errors should not start with capital letters (excluding proper nouns, acronyms, or initialism)
|
|
- errors should not end with punctuation
|
|
- these restrictions do not apply to logging, only the error type itself
|
|
|
|
### Configuration Documentation
|
|
|
|
The configuration documentation has a consistent format this section describes it as best as possible. It's recommended
|
|
to check additional sections for examples.
|
|
|
|
#### Layout
|
|
|
|
The first thing in the configuration documentation should be a description of the area. This is promptly followed by the
|
|
configuration heading (h2 / indent 2) which has an example full configuration.
|
|
|
|
Under the configuration example each option in the configuration needs to be documented with its own heading
|
|
(h3 / indent 3). Immediately following the heading is a div with some stylized icons.
|
|
|
|
The body of the section is to contain paragraphs describing the usage and information specific to that value.
|
|
|
|
|
|
**Example Stylized Icons:**
|
|
|
|
```html
|
|
<div markdown="1">
|
|
type: string
|
|
{: .label .label-config .label-purple }
|
|
default: example
|
|
{: .label .label-config .label-blue }
|
|
required: no
|
|
{: .label .label-config .label-green }
|
|
</div>
|
|
```
|
|
|
|
##### type
|
|
|
|
This section has the type of the value in a semi human readable format. Some example values are `string`, `integer`,
|
|
`boolean`, `list(string)`, `duration`. This is immediately followed by the styles `.label`, `.label-config`,
|
|
`.label-purple`.
|
|
|
|
##### default
|
|
|
|
This section has the default of the value if one exists, this section can be completely omitted if there is no default.
|
|
This is immediately followed by the styles `.label`, `.label-config`,
|
|
`.label-blue`.
|
|
|
|
##### required
|
|
|
|
This section has the required status of the value and must be one of `yes`, `no`, or `situational`. Situational means it
|
|
depends on other configuration options. If it's situational the situational usage should be documented. This is
|
|
immediately followed by the styles `.label`, `.label-config`, and a traffic lights color label, i.e. if yes `.label-red`,
|
|
if no `.label-green`, or if situational `.label-yellow`.
|
|
|
|
### Storage
|
|
This section outlines some rules for storage contributions. Including but not limited to migrations, schema rules, etc.
|
|
|
|
#### Migrations
|
|
All migrations must have an up and down migration, preferably idempotent.
|
|
|
|
All migrations must be named in the following format:
|
|
```text
|
|
V<version>.<name>.<engine>.<direction>.sql
|
|
```
|
|
|
|
##### version
|
|
A 4 digit version number, should be in sequential order.
|
|
|
|
##### name
|
|
A name containing alphanumeric characters, underscores (treated as spaces), hyphens, and no spaces.
|
|
|
|
##### engine
|
|
The target engine for the migration, options are all, mysql, postgres, and sqlite.
|
|
|
|
#### Primary Key
|
|
All tables must have a primary key. This primary key must be an integer with auto increment enabled, or in the case of
|
|
PostgreSQL a serial type.
|
|
|
|
#### Table/Column Names
|
|
Table and Column names must be in snake case format. This means they must have only lowercase letters, and have words
|
|
seperated by underscores. The reasoning for this is that some database engines ignore case by default and this makes it
|
|
easy to be consistent with the casing.
|
|
|
|
#### Context
|
|
All database methods should include the context attribute so that database requests that are no longer needed are
|
|
terminated appropriately.
|