CoMPAS Contributing

Contributing guide, code of conduct and more.

Currently v0.0.1

© 2025. All rights reserved.

Edit on GitHub!

Developing for CoMPAS

Table Of Contents

CoMPAS components

CoMPAS is composed of multiple components, each designed to fulfill a specific role within the project. The following is an overview of these components, their description, and their associated repositories.

Local development

This section provides instructions for setting up a local development environment and running the CoMPAS stack or individual services.

Prerequisites

Ensure the following tools are installed on your system:

Running the CoMPAS stack locally

To run the entire CoMPAS stack locally, you can use the compas-deployment repository, which provides a pre-configured docker-compose-postgresql.yml file. Follow these steps:

  1. Clone the compas-deployment repository:
git clone https://github.com/com-pas/compas-deployment.git
cd compas-deployment
  1. To build and start all services run:
docker-compose --env-file compas/.env -f compas/docker-compose-postgresql.yml up -d --build
  1. Use the ./bin/docker-wait-on-containers.sh script to wait for all containers to be fully initialised. Once all containers are ready, it will print a message indicating that no containers are in the health=starting state.
./bin/docker-wait-on-containers.sh

  1. Once the stack is running, the application will be available at http://localhost. You can log in using the credentials configured in the Keycloak demo setup. For more information on the Keycloak users that are created, refer to the Keycloak Demo Configuration documentation. If you encounter any issues, refer to the Known Issues section in the compas-deployment repository.

  2. To stop the stack, run:

# Stop all containers
docker-compose -f compas/docker-compose-postgresql.yml down

or

# Stop all containers and remove the volumes.
docker-compose -f compas/docker-compose-postgresql.yml down -v

Running an individual service locally

Each repository contains the relevant and most up-to-date information on setting up the development environment and running the service locally. Refer to the DEVELOPMENT.md file or equivalent documentation in the respective repository for detailed instructions.

Component Development Guide
CoMPAS Open SCD Development Guide
CoMPAS SCL Data Service Development Guide
CoMPAS CIM Mapping Development Guide
CoMPAS SCL Validator Development Guide
CoMPAS SCL Auto Alignment Development Guide
CoMPAS Core Not available
CoMPAS SCT Not available
CoMPAS SCL XSD Not available
CoMPAS Deployment Development Guide

Tooling

GitHub

What’s GitHub? It’s where you’re looking right now! (Joking!).

We are using GitHub for hosting our Git repositories. GitHub is being used for creating issues and creating Pull Requests to review / merge each other’s code.

GitHub User Settings

We noticed that there are sometimes problems with the DCO Check. This can be caused by an email setting of the user. It’s about keeping the email address private.

Go to Settings of your account and select the option Emails. Here you will find the setting Keep my email addresses private. Uncheck this setting. When checked there are cases that the DCO Check will fail, because the github.com email address is used in the Web interface. When failing it will cause a lot of work to fix it.

LFX Security Tool

For checking potential security issues, we use the LFX Security Tool. The LFX Security Tool scans selected repositories for potential security issues in dependencies. It also scans every license that is being used within a repository and checks if they are compatible within open source projects.

SonarCloud

CoMPAS is using SonarCloud for static code analysis. Every GitHub repository has a GitHub Action which automatically pushes the code to SonarCloud with a frequency of the given GitHub Action (most of the time on each push).

A Pull Request can’t be merged before all SonarCloud issues are being fixed!

GitHub Packages

To make artifacts available between the different GIT repositories we are using GitHub Packages to distribute these. Every GIT repository can build its artifacts and publish these to GitHub Packages. Other GIT repositories can then add GitHub Packages as Maven repository to their build tool. See below how to do both action for the specific tools.

To use GitHub Packages a username and token is needed. The username is your GitHub username. The token can be generated in GitHub by going to your settings, Developer settings, Personal access tokens. Generate a new token here and make sure that the scope “read:packages” is enabled. Use this token below to configure the build tools.

Basic Maven

The project uses Maven to manage the build. Most projects use multi-module structures to build all code. A basic command to run Maven is:

$ maven clean verify

GitHub Packages in Maven

To use GitHub Packages in Maven an extra repository need to be added to the build process.

<repositories>
    <repository>
        <id>github-packages-compas</id>
        <name>GitHub Packages CoMPAS</name>
        <url>https://maven.pkg.github.com/com-pas/*</url>
    </repository>
</repositories>

Because credentials are needed for GitHub Packages, these will be passed by using the Settings.xml file.

Maven Local Settings.xml for GitHub Packages

Edit (or create if not already exists) the ~/.m2/settings.xml file and add the following content:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              http://maven.apache.org/xsd/settings-1.0.0.xsd">
  
    <servers>
        <server>
            <id>github-packages-compas</id>
            <username>username</username>
            <password>password</password>
        </server>
    </servers>
  
</settings>

Add this server section. The ID of the server must be the same as the ID found in the previous repository ID, it should map. Username should be your GitHub username, password can both be your own encrypted password or a Personal Access Token.

IDEs

If your IDE is supported by SonarLint (both IntelliJ IDEA and the Eclipse IDE are supported), it is recommended to install it. It provides immediate feedback on most sonar issues. Running tests individually is often possible in IDEs without invoking maven. Please consult the documentation of your IDE for setting up the project through maven integration.

For MapStruct there are plugins available for both IDEs mentioned below. See this page.

Intellij IDEA

Import the project using IDEA’s maven integration in the GUI. Install SonarLint. Code!

Eclipse IDE

Eclipse IDE has two ways to import maven projects: the eclipse GUI component m2e that understands maven or the maven CLI component maven-eclipse-plugin.

Using maven-eclipse-plugin, it is possible to recreate all the necessary eclipse files from scratch. A practical way to use it and get deterministic results is to remove all existing eclipse files, delete all eclipse projects from the workspace, regenerate all the eclipse files and reimport everything into eclipse as “existing eclipse projects”. If all your projects are checked out outside of the eclipse workspace on the file system, then deleting all the projects is even simpler because you can just delete the whole workspace. The whole cycle takes only a few seconds.

# Ensure that eclipse is not running
# delete the projects in the GUI, or "rm -rf" all eclipse projects from the workspace
# delete all eclipse files from the file system
$ find . -name .project -o .classpath -o -name .settings -exec rm -rf '{}' \;
# regenerate eclipse files
$ mvn package eclipse:eclipse
# import as existing eclipse projects in the GUI (alternatively, use eclim's :ProjectImportDiscover directly from ViM)

After importing the projects with either method, install SonarLint for quicker feedback on potential sonar issues.

Others

Adding custom badges to your README

Badges are great for quickly checking several status reports of a specific repository. Sometimes a application doesn’t serve badges (LFX Security tool for example), and you need to do it yourself. We use shields.io for this problem.

In case of the LFX Security Tool, we used the following: