Coding Conventions and Guidelines
Here you find an overview of our conventions on coding and version control.
Also have a look at our Contribution Guidelines.
We use GitHub Flow
mainbranch 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 format. Remind yourself to update the
CHANGELOG.mdbefore committing code. Remember that changelogs are meant for humans and should reflect the end-user value. When doing a release 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 falseto use recursive as your default merge strategy
We use conventional commits
Mention related ticket IDs where applicable, like
play#123when cross-referencing between repositories. For example you can close tickets by using
Use atomic commits
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.
ECMAScript and TypeScript
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”.
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.
Test and Demo Instances
We have two instances which are automatically and transparently deployed using GitLab:
dashboard.aura.radio - Developer/Testing instance holding the latest codebase of the
demo.aura.radio - Demo instance with a stable release, based on a release tag configured in GitLab.
We use the gitlab-ci for Deploying specific versions of aura.
You Can adjust the Container versions at gitlab-ci
AURA_STEERING_VERSION: "main" AURA_TANK_VERSION: "main" AURA_DASHBOARD_VERSION: "main" AURA_DASHBOARD_CLOCK_VERSION: "main"
you can choose between Docker Registry or Gitlab-Registry at gitlab-ci
DOCKER_REGISTRY: "docker"for Docker hub
DOCKER_REGISTRY: "gitlab"for Gitlab registry
After committing your desired changes, Gitlab auto deploy this version. Note that the Pipeline will only run on protected branches.
When a new Tagged Release is published, Gitlab will deploy this release.
There is a
manual apply before deploy to ensure all Container Images with this Tag are published.
Apply then Docker Images are released!
Auto Deployment based on feature branches
While this is currently not used, the Auto Deployment feature also provides custom builds based on feature branches.
For all components, feature branches automatically build Docker containers and push them to the gitlab-registry.
To roll out new features, the Compose-File, must be set to the corresponding tag of the feature branch.
After the commit, the version will be rolled out automatically.
The general documentation is located in
aura/docs and hosted at docs.aura.radio. When working on any component, also check if this documentation has to be updated or extended.
For development, we recommend the native installation as outlined in the
README of individual repositories.
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:
Order of configuration
After that, you need to configure the projects in following order:
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.
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.
For more detailed documentation read the
README files in the individual repositories.
You get an overview of all repositories at code.aura.radio.