# Coding Style Guide

Here you find an overview of our coding conventions and style guide.

Also have a look at our [Contribution Guidelines](../contribute/contributions.md).

## Semantic Versioning

Release names are defined according to the [SemVer 2.0.0](https://semver.org/) versioning scheme.

```{admonition} Semantic versioning of releases in CI/CD Pipelines
:class: tip

The chosen git tag will be the release name and the version of the Docker Image. Therefore the
pipeline script will enforce it to conform to [Semantic Versioning 2.0.0](https://semver.org/).
```

## Keep a Changelog

For changelogs we use the format suggested by [Keep a Changelog](https://keepachangelog.com/).
Try to follow best practices when writing the changelog. But remember, changelogs are for humans.
So do apply best practices when compiling your changelog.

The general AURA changelog is located in `CHANGELOG.md`.

Additionally, all individual service repositories hold their own changelog file. At each release
they are bundled in the `aura/changelog` directory.

When writing changelogs think about to

- Use **`Breaking:`** prefixes to indicate breaking changes.
- Use **`Known Issue:`** prefix to indicate a known problem and point to a workaround, if available.
- Avoid multi-line statements which include line-breaks. This breaks the release script.
- Clarity over quantity, because changelogs are for humans.

```{admonition} Changelogs are for humans!
:class: alert
Avoid any technical details on internals. But documenting API or CLI changes are okay. Try to read
it from a end-user perspective. Learn more at [keepachangelog.com](https://keepachangelog.com/).
```

## git

- We use [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow)
- Keep the `main` branch stable, as releases are derived from it. When contributing a breaking change, like API changes, inform the team about the intended merge.
- When contributing code, create a _Merge Request_, and assign the repository maintainer for review. Do not _squash commits_ when performing the merge.
- We write changelogs in the [keep a changelog](https://keepachangelog.com/) format. Remind yourself to update the `CHANGELOG.md` before committing code. Remember that changelogs are meant for humans and should reflect the end-user value. When [doing a release](releases.md) we use the changelog as our _Release Notes_. When providing code via a _Merge Request_ the maintainer will remind you to update the changelog too :-)
- Avoid crunching commits and rebasing; set `git config pull.rebase false` to use _recursive_ as your default merge strategy
- We use [_conventional commits_](https://www.conventionalcommits.org/)
- Mention related ticket IDs where applicable, like `#123` or `play#123` when cross-referencing between repositories. For example you can close tickets by using `closes #123`.
- Use [atomic commits](https://www.freshconsulting.com/insights/blog/atomic-commits/)

## Code

### Python

We use [Black](https://github.com/psf/black/) with default settings, enforced by [Flake8](https://flake8.pycqa.org/en/latest/).

We use the default settings, except for a maximal line-length of 99 characters. If you are using
a Black IDE integration, think about adapting its settings.

For code documentation we use the [Flake8 Docstrings](https://pypi.org/project/flake8-docstrings/) extension with [Google-style formatting](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) enabled (`docstring-convention=google`).

### ECMAScript and TypeScript

We use [ESLint](https://eslint.org/) as the common Linter. When your code is based on [VueJS](https://vuejs.org/) or [Svelte](https://svelte.dev/), install the official IDE extensions. These extensions provide additional style checks and auto-formatting options.

## API

We use OpenAPI 3 specs to describe our APIs. Learn more in the
[Developer Guide > API](api/index.md) chapter and find the detailed OpenAPI 3 specs at
[api.aura.radio](https://api.aura.radio).

## Testing

When providing new features or refactoring code, please provide test cases. We do not expect
100% test coverage but are aiming for having the most important usage scenarios covered by
automated CI/CD test suites.

## Documentation

The general documentation is located in `aura/docs` and hosted at [docs.aura.radio](https://docs.aura.radio). When working on any component, also search for relevant parts of the documentation that may need to be updated or extended.