Development

Coding Conventions and Guidelines

Here you find an overview of our conventions on coding and version control.

git

We use GitHub Flow
Keep the main branch stable, as releases are derived from it
Avoid crunching commits and rebasing; set git config pull.rebase false to use recursive as your default merge strategy
We use the seven rules of a great Git commit message, and optionally conventional commits
Mention related ticket IDs where applicable, like #123 or play#123 when cross-referencing between repositories
Use atomic commits

Python

We use Black with default settings, enforced by Flake8.

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 extension with Google-style formatting enabled (docstring-convention=google).

ECMAScript and TypeScript

We use ESLint as the common Linter. When your code is based on VueJS or Svelte, install the official IDE extensions. These extensions provide additional style checks and auto-formatting options.

API

We utilize an API-first approach. APIs are specified using OpenAPI 3. Find the API at api.aura.radio.

All the main aspects are documented within the spec. In some cases you may need some additional documentation in the docs. For example the API: Schedules and conflict resolution document can be found in “Developer Guide -> Misc”.

API-first

At the moment only Engine API is based on API-first. Steering API and Tank API are momentarily generated out of the code base.

Documentation

The general documentation is located in meta/docs and hosted at docs.aura.radio. When working on any component, also check if this documentation has to be updated or extended.

Developer Installation

For Development the native installation as outlined in the README of individual repositories recommended.

Docker Compose Deployments

For production we highly recommend to run AURA using Docker and Docker Compose as outlined in the Administration Guide. But also as a developer you can benefit from the ease of an Docker Compose installation. For example when developing some Engine feature, you may want to run AURA Web with Docker Compose while testing.

Prepare your Development Environment

It is recommended to clone all projects for example in such folder structure:

~code/aura/aura
~code/aura/steering
~code/aura/dashboard
~code/aura/engine
~code/aura/engine-api
~code/aura/engine-core
...

Order of configuration

After that, you need to configure the projects in following order:

Web Projects

Steering - Administration interface for schedules and programme information.
Dashboard - Frontend to manage schedules, program info and audio files.
Tank - Upload, pre-processing and storage of the audio files.
…

Play-out Projects

Engine Core - Playout-engine to deliver the actual radio to the audience.
Engine API - API Server to provide playlogs and information for the studio clock.
Engine - Scheduling and remote control for the playout-engine.
…

Configuring the OpenID Clients

Dashboard and Tank authenticate against Steering using OpenID. We use OpenID Connect (OIDC) to implement OpenID.

Check out the OIDC configuration page, on how to get them talk to each other.

Component Documentation

For more detailed documentation read the README files in the individual repositories.

You get an overview of all repositories at code.aura.radio.