Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Repositories overview #1295

Open
wants to merge 1 commit into
base: introduce-docs
Choose a base branch
from
Open

Repositories overview #1295

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion docs/source/project-structure.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
Project structure
=================
TBD

The **Leapp Project** provides the framework for automating in-place upgrades from one major version of Red Hat Enterprise Linux to another. It is organized into a set of modular components, each responsible for specific tasks during the upgrade process. These components are managed across multiple **repos**, logically grouped to facilitate upgrades between different RHEL paths.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, I would not speak about the leapp project as again that's a different repository. Leapp can be used also for different purposes and as it is, it does not know anywhine about upgrades at all. That's one of reasons why these two projects / repositories are separated. This (upgrade) project is just using the leapp framework and tooling to achieve the goal.


This documentation explains the structure of the **Leapp repository** and provides guidance on how to determine where to place new entities, such as actors, models, and libraries, within the project.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This documentation explains the structure of the **Leapp repository** and provides guidance on how to determine where to place new entities, such as actors, models, and libraries, within the project.
This documentation explains the structure of this git repository and provides guidance on how to determine where to place new entities, such as actors, models, and libraries, within the project.

Well, the name is not the best one, but we have to live with it. Phrase the leapp repository would be speaking in current terminology about one specific leapp repository (e.g. system_upgrade_el7toel8) or the actual leapp git repositoriy. So let's use either

  • of this project
  • of this git repository
  • of the leapp-repository git repository


.. toctree::
:maxdepth: 4
Expand Down
48 changes: 48 additions & 0 deletions docs/source/repositories.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Repositories Overview

The **Leapp** project uses a modular repository structure in `repos/system_upgrade` to support multiple upgrade paths
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The **Leapp** project uses a modular repository structure in `repos/system_upgrade` to support multiple upgrade paths
This project uses a modular repository structure in `repos/system_upgrade` to support multiple upgrade paths

Well, I would not speak here about how the leapp framework works. The leapp project is reference actually to the leapp git repository and so to the framework or tooling. In this case, we could speak more e.g. about the upgrade project unless we add in future more stuff unrelated to the upgrade. So far, there is no such expectation so saying the upgrade project would work too.

and shared functionality across these paths.
Each repository contains actors, models, workflows,
and supporting code for a specific upgrade path or common functionality.

## High-Level Structure
```
repos/
├── system_upgrade/
│ ├── common/
│ ├── el7toel8/
│ ├── el8toel9/
│ └── el9toel10
│ └── ...
```
## Main Repositories

- **`repos/system_upgrade/common/`**: Contains shared code that applies to all in-place upgrades,
regardless of the specific source and target versions.
- **`repos/system_upgrade/elXtoelY/`**: Contains code specific to concrete upgrade path.
Comment on lines +20 to +22
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the upgrade path is usually understood as X.Y -> X1.Y1, where elXtoelY coveres all upgrade paths from X to Y. I would consider it ok, but some people could be confused by different wording / meaining in different parts of the documentation (and official RH docs). So instead of speaking about upgrade path, I would rather say something like:

Suggested change
- **`repos/system_upgrade/common/`**: Contains shared code that applies to all in-place upgrades,
regardless of the specific source and target versions.
- **`repos/system_upgrade/elXtoelY/`**: Contains code specific to concrete upgrade path.
- **`repos/system_upgrade/common/`**: Contains shared code that applies to all in-place upgrades,
regardless of the specific source and target versions.
- **`repos/system_upgrade/elXtoelY/`**: Contains code specific for in-place upgrades between EL X and EL Y systems.

Note that we do not want to use esplicitely RHEL in upstream documentation, as we would like to cover in future also CentoStream, and other forks using this project handles additional distributions. So going this more generic way seems to me better.


## How to Determine Where to Place a New Entity?

When developing a new actor, model, or library, use the following guidelines to determine where to place it:

- **Determine the Upgrade Path**:
- Is the functionality specific to a certain upgrade path?
- If your entity is related to upgrading specific paths, place it in repos/system_upgrade/elXtoelY/.

- **Is It Generic or Reusable Across Upgrade Paths?**:
- If the entity is not specific to any one upgrade path and can be reused across multiple upgrades
(e.g., system checks, disk space validation, network settings), place it in the repos/system_upgrade/common/ repository.

- **Classify by Type**:
- Actor: If you’re creating an actor,
place it in the actors/ directory of the appropriate repository (version-specific or common).
- Model: If it’s a data structure shared between actors, place it in the models/ directory of the relevant repository.
- Library: Utility functions that support actors go in the libraries/ directory.
Comment on lines +36 to +40
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure whether to keep this part. This is something what is generic and seems to me like something that should be covered by the leapp documentation. It's not possible to put an actor e.g. into models directory, etc. Models are always shared between actors. However, when speaking about libraries, it's a question whether it should be an actor's private library or shared library inside a specific leapp repository. But not sure whether to cover this one specific case in this particular section.


- **Use Existing Tags When Appropriate**:
- When creating new actors, consider using existing tags (such as PreUpgrade, PostUpgrade, etc.)
to categorize when the actor should be executed during the upgrade.
Comment on lines +42 to +44
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would drop this. this is something what i would keep on other tutorials - e.g. how to create actor. also, there are no such tags. I would focus here just on stuff related to Where questions. Instructions about what tags should be used in actors should be rather covered by tutorials focused on creation of actors.


Using changes in the Leapp repositories to perform an in-place upgrade involves modifying or adding new actors, models,
and workflows, building the modified repository, and using the Leapp tool to execute the upgrade. After integrating your changes, the upgrade process runs seamlessly with the customizations you've added,
ensuring the system is upgraded according to your specifications.
Comment on lines +45 to +48
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking about this, it seems it's an information that should be presented in best-practices or something like that. This part of docs should cover the structure of this project, so it seems to me as out of the contect or scope of this part.