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.8

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

pyenv install 3.8.20

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 py38

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

Before building a docker image, clean up the project to reduce image size.
tox command caches a lot of files that might be over 500MB.

make clean

Useful commands

Display list of installed virtual environments

pyenv virtualenvs

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

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

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.8.20