A guide for new contributors

Install Environment

The required languages and tools to work on the project are specified in the .tools_version file in the root folder.

Nonetheless, docker or podman must be available in your environment

asdf related documentation can be found here.

IntelliJ Setup

Plugins

Plugins to be installed are :

  • Adapter for Eclispe Code Formatter

  • SonarLint

  • AsciiDoc

  • PlantUml Integration

Eclipse Code Formatter

Open the Preferences (or Settings) window and navigate to Adapter for Eclipse Code Formatter section on the left pane.

Select Use Eclipse’s Code Formatter, then change the Eclipse workspace/project folder or config file to point to:
provoly-hypervisor-back/ide-config/src/main/resources/eclipse-format.xml.

Make sure the Optimize Imports box is ticked. Then, select Import Order from file and make it point to directory :
provoly-hypervisor-back/ide-config/src/main/resources .

Next, disable wildcard imports: navigate to Editor → Code Style → Java → Imports and set Class count to use import with '\*' to 5.

Do the same with Names count to use static import with '*'.

SonarLint

Extension which finds and fixes coding issues in real-time.

AsciiDoc

Our technical documentation uses the plain text markup language AsciiDoc.

After that, you have to enable soft wraps for the asciiDoc files : general → editor → softwrap → *.adoc

Run the formatter manually

The following command must be run in the root folder before committing on repository :

mvn compile

or

mvn spotless:apply

When submitting a merge request the CI build will fail if the code isn’t properly formatted, so it is recommended that you always run a full Maven build before submitting a pull request.

Architecture documentation

The architecture documentation uses Structurizr.

An extended documentation can be found here.

Simply run in root directory:

docker run --rm -v ./docs/structurizr:/usr/local/structurizr -p 9191:8080 structurizr/lite:2024.01.02

As of now, exporting as svg is done as described here

Running locally

Hypervisor is configured to launch multi devservices at start:

Keycloak

The hypervisor leverages the keycloak devservice, with a custom realm settings for its oidc provider.

Access the admin console with the user admin:admin

The application’s realm is hypervisor, it has three users:

  • iamsuperadmin:password // every roles

  • iamadmin:password // every roles

  • reader:letmein // reader roles

Postgresql

No configuration is provided, so the default quarkus configuration is used.

By default, all devservices are stopped when application stops, and no data are kept. To use same containers accorss restarts, see here.

Kafka

It’s possible to manage kafka topics thanks to the Quarkus dev ui.

Check list

  1. If your feature modifies the API. You have to mirror the impacts the src/main/resources/META-INF/resources/openapi.yaml file.

  2. If your feature impacts the database model, you changes must be placed under the src/main/resources/db/migration folder. You also have to mirror the impacts on the diagram in docs/modules/architecture/partials/diagrams/mcd.puml. We aim to keep it simple (stupid), just the concepts relations.

  3. If your feature adds or removes user roles, you have to mirror those changes in the realm json file the renovate.json file.