developer_guide.md

Developer Guide

Table of Contents

• Developer Guide
  • Table of Contents
  • Introduction
  • Setup Development Environment
    • Generic Steps
      • Install make
      • Install pyenv
      • Install Python
      • Install setuptools
      • Install tox
    • Module Specific Steps
      • Create a virtual environment
      • Activate the virtual environment
  • Development Workflow
    • Run lint checks, type checking, and tests
    • Run lint checks only
    • Run type checking only
    • Run tests only
  • Creating a pull request
    • Prerequisites
    • Branch naming, PRs, and commit messages
  • Building a docker image
  • Useful commands
    • Display list of installed virtual environments
    • Deactivate the virtual environment
    • Remove the virtual environment:
    • Display the list of installed Python versions:
    • Remove the Python version:

Introduction

This document provides a guide for developers to set up their development environment and contribute to the project.
Steps consists of generic steps that are required only once, and module-specific steps that are required for each module. The document also provides information on how to contribute to the project.

Setup Development Environment

Generic Steps

The following steps are required only once when setting up the development environment.

Install make

sudo apt install make

Install pyenv

Note

For up-to-date installation instructions, please refer to official website

curl https://pyenv.run | bash

Install Python

To get a list of latest Python versions available:

pyenv install --list | grep 3.10

Currently, the latest version is 3.10.19. To install it:

pyenv install 3.10.19

Set the global Python version to 3.10.19:

pyenv global 3.10.19

Install setuptools

pip install setuptools

Install tox

Note

If tox is installed globally, it will be available for all virtual environments.
If it's not installed globally, you will need to install it for each virtual environment.

pip install tox

Module Specific Steps

The following steps are required for each module when setting up the development environment.

Create a virtual environment

Note

Replace collector with the module's name

pyenv virtualenv collector

Activate the virtual environment

Note

Replace collector with the module's name

pyenv activate collector

Development Workflow

After following the setup steps, you can start developing the module. The following commands are available for each module.

Run lint checks, type checking, and tests

The following command will run lint checks, type checking, and tests:

tox

Run lint checks only

tox -e lint

Run type checking only

tox -e type

Run tests only

tox -e py310

Creating a pull request

Prerequisites

Important

When opening a pull request, please provide a signed Contributor Licence Agreement (CLA). More information can be found here.

For each module, run tox to make sure that the code is linted, typed, and tested.

tox

For each module, make sure that the license headers are up to date using this command:

make license

Branch naming, PRs, and commit messages

Please follow the style guide for branch names, PRs, and commit messages as described in the style guide.

Building a docker image

To build a docker image or run module(s) in docker, please refer to Docker README.

Packaging modules

In order to create .deb packages for a module, each module is built inside a controlled Docker environment that reproduces the target Ubuntu release. The Dockerfile installs all required build tools and dependencies, compiles the module, and uses Debian’s packaging utilities such as dpkg-buildpackage to generate the .deb file. This ensures consistent, reproducible builds that match the expected distribution environment.

Replace <module_name> with the actual name of your module and <jammy|noble> with the target Ubuntu version you want to build for.

You can build a module package using:

docker buildx build --build-arg MODULE_NAME=<module_name>_module . --target=artifacts --output type=local,dest=./output -f Dockerfile_<jammy|noble>

Then you can check the created package for compliance with the Debian policy and for other common packaging errors using:

lintian *.deb

Useful commands

Display list of installed virtual environments

pyenv virtualenvs

An example output:
The * indicates which virtualenv is active.

  3.10.16/envs/collector (created from /home/xrduser/.pyenv/versions/3.10.16)
* collector (created from /home/xrduser/.pyenv/versions/3.10.16)

Deactivate the virtual environment

pyenv deactivate

Remove the virtual environment

pyenv virtualenv-delete collector

Display the list of installed Python versions

pyenv versions

Remove the Python version

pyenv uninstall 3.10.19