Development Guide

How the tool works in general

In the main scenario, the tool performs a series of checks and preparation actions prior to the conversion. It then proceeds to execute the conversion itself and performs post-actions afterwards. This entire process can be divided into a set of small components. These components are described using an abstract Action class. The actions are aggregated within an ActionFlow, which iterates through them and executes them one by one. Details about actions could be found in the related article.

Stages

The conversion process is divided into four stages:

1. Precheck - This stage involves checking if all the required conditions are met before starting the conversion. Parts of this stage are implemented by classes inherited from CheckAction. The flow class responsible for this stage is CheckFlow. The related function in main.py is is_required_conditions_satisfied.
2. Preparation - In this stage, all the necessary changes are made on the system prior to the conversion. Parts of this stage are implemented by classes inherited from ActiveAction. The flow class responsible for this stage is PrepareActionsFlow. At the end of this stage, the system needs to be rebooted to initiate the conversion process.
3. Conversion - This stage is the core of the leapp itself, where the actual conversion takes place. We have no control over this process and simply wait until it is completed.
4. Finish - In this stage, all the necessary post-conversion changes are made on the system. It's important to note that in this stage, we are already working inside AlmaLinux. Parts of this stage are implemented by classes inherited from ActiveAction. The flow class responsible for this stage is FinishActionsFlow. At the end of this stage, the system needs to be rebooted to enter a normal working state.

Source Code Structure

The source code is divided into two main parts: actions and common.

The actions part can be found in the "actions" directory. It includes abstract classes for actions and flows, as well as all the necessary implementations of actions. If you want to add a new action, please place it in this directory. For more details, refer to the "Actions" article..

The common part is located in the "common" directory. It contains common functions and classes that can be utilized in actions. If you notice that several actions share similar logic, it is recommended to move that logic into the common section and add some unit tests. More information can be found in the "Common Functions" section below.

Common Functions

The common functions serve as a library for your actions, providing common functionalities that are used across multiple actions. Here's what we have:

• files: Performs actions related to file manipulation, such as adding strings, changing strings, reading from files, or creating backups.
• leapp_configs: Allows manipulation of the Leapp configuration by adding repositories or changing package action information.
• log: Provides logging capabilities to write logs based on Python's logging module.
• messages: Contains a collection of messages that are displayed to the user.
• motd: Provides functions for manipulating the message of the day (MOTD) by adding or removing strings.
• plesk: Contains functions for interacting with specific Plesk functions, such as informing Plesk services about conversion errors or retrieving Plesk version information.
• rpm: Performs typical RPM-related actions, such as checking if a package is installed or removing it.
• util: Includes various utility functions that do not fit into any specific category. Currently, it primarily consists of a function called logged_check_call that executes subprocess commands and writes the output to the log.
• writer: Contains classes for routing output to different streams or files.

Unit tests

The tests are stored in the /tests directory. It is highly recommended to add tests when introducing new functions to the common module in the common directory.

General Advice

• When modifying files during the conversion process, it is recommended to use the backup_file, restore_file_from_backup, and remove_backup functions from the common/files.py module. By doing so, it becomes easier to revert the changes during the revert or finish stage.
• If you want to add a message to the MOTD (Message of the Day) at the finishing stage, please use the add_finish_ssh_login_message function. In most cases, you do not need to use publish_finish_ssh_login_message as it is already called in the necessary locations.
• Please make sure to use logged_check_call from the common/utils.py module when you need to execute a utility. This is necessary because it saves the standard output (stdout) into the centos2alma logs, which can be helpful for future investigations.
• Consider moving logic from new actions to common modules, if possible. This allows for easier testing during unit tests.