docs: Add doc about community upgrades

matejmatuska · yuravk · commit edea7e0ce19b · 2025-11-28T13:12:08.000+02:00
The existing coding and PR workflow guidelines are split into separate pages under "Contrbuting" and the new doc is added there as well. Jira: RHEL-110563 (cherry picked from commit eabab8c)
diff --git a/docs/source/contributing/coding-guidelines.md b/docs/source/contributing/coding-guidelines.md
@@ -1,5 +1,4 @@
-# Contribution and development guidelines
-## Code guidelines
+# Coding guidelines
 
 Your code should follow the [Python Coding Guidelines](https://leapp.readthedocs.io/en/latest/contributing.html#follow-python-coding-guidelines) used for the leapp project. On top of these rules follow instructions
 below.
@@ -84,53 +83,3 @@ guaranteed to exist and executable.
 The use of the {py:mod}`subprocess` library is forbidden in leapp repositories.
 Use of the library would require very good reasoning, why the
 {py:func}`~leapp.libraries.stdlib.run` function cannot be used.
-
-## Commits and pull requests (PRs)
-### PR description
-The description should contain information about all introduced changes:
-* What has been changed
-* How it has been changed
-* The reason for the change
-* How could people try/test the PR
-* Reference to a Jira ticket, Github issue, ... if applicable
-
-Good description provides all information for readers without the need to
-read the code. Note that reviewers can decline to review the PR with a poor
-description.
-
-### Commit messages
-When your pull-request is ready to be reviewed, every commit needs to include
-a title and a body continuing a description of the change --- what problem is
-being solved and how. The end of the commit body should contain Jira issue
-number (if applicable), GitHub issue that is being fixed, etc.:
-```
-  Commit title
-
-  Commit message body on multiple lines
-
-  Jira-ref: <ticket-number>
-```
-
-Note that good commit message should provide information in similar way like
-the PR description. Poorly written commit messages can block the merge of PR
-or proper review.
-
-### Granularity of commits
-The granularity of commits depends strongly on the problem being solved. However,
-a large number of small commits is typically undesired. If possible, aim a
-Git history such that commits can be reverted individually, without requiring reverting
-numerous other dependent commits in order to get the `main` branch into a working state.
-
-Note that commits fixing problems of other commits in the PR are expected to be
-squashed before the final review and merge of the PR. Using of `git commit --fixup ...`
-and `git commit --squash ...` commands can help you to prepare such commits
-properly in advance and make the rebase later easier using `git rebase -i --autosquash`.
-We suggest you to get familiar with these commands as it can make your work really
-easier. Note that when you are starting to get higher number of such fixing commits
-in your PR, it's good practice to use the rebase more often. High numbers of such
-commits could make the final rebase more tricky in the end. So your PR should not
-have more than 15 commits at any time.
-
-### Create a separate git branch for your changes
-TBD
-
diff --git a/docs/source/contributing/community-upgrades.md b/docs/source/contributing/community-upgrades.md
@@ -0,0 +1,39 @@
+# Community upgrades for Centos-like distros
+
+In the past, this project was solely focused on Red Hat Enterprise Linux upgrades. Recently, we've been extending and refactoring the `leapp-repository` codebase to allow upgrades of other distributions, such as CentOS Stream and also upgrades + conversions between different distributions in one step.
+
+This document outlines the state of support for upgrades of distributions other than RHEL. Note that support in this case doesn't mean what the codebase allows, but what the core leapp team supports in terms of issues, bugfixes, feature requests, testing, etc.
+
+RHEL upgrades and upgrades + conversions *to* RHEL are the only officially supported upgrade paths and are the primary focus of leapp developers. However, we are open to and welcome contributions from the community, allowing other upgrade (and conversion) paths in the codebase. For example, we've already integrated a contribution introducing upgrade paths for Alma Linux upgrades.
+
+This does not mean that we won't offer help outside of the outlined scope, but it is primarily up to the contributors contributing a particular upgrade path to maintain and test it. Also, it can take us some time to get to such PRs, so be patient please.
+
+Upon agreement we can also update the upgrade paths (in `upgrade_paths.json`) when there is a new release of the particular distribution. However note that we might include some upgrade paths required for conversions *to* RHEL on top of that.
+
+Contributions improving the overall upgrade experience are also welcome, as they always have been.
+
+```{note}
+By default, upgrade + conversion paths are automatically derived from upgrade paths. If this is not desired or other paths are required, feel free to open a pull request or open a [discussion](https://github.com/oamg/leapp-repository/discussions) on that topic.
+```
+
+## How to contribute
+
+Currently, the process for enabling upgrades and conversions for other distributions is not fully documented. In the meantime you can use the [pull request introducing Alma Linux upgrades](https://github.com/oamg/leapp-repository/pull/1391/) as reference. However, note that the leapp upgrade data files have special rules for updates, described below.
+
+### Leapp data files
+
+#### repomap.json
+
+To use correct target repositories during the upgrade automatically, the `repomap.json` data file needs to be updated to cover repositories of the newly added distribution. However, the file cannot be updated manually as its content is generated, hence any manual changes would be overwritten with the next update. Currently there is not straightforward way for the community to update our generators, but you can
+
+- submit a separate PR of how the resulting `repomap.json` file should look like, for an example you can take a look at [this PR](https://github.com/oamg/leapp-repository/pull/1395)
+- or provide the list of repositories (possibly also architectures) present on the distribution
+
+and we will update the generators accordingly, asking you to review the result then. We are discussing an improvement to make this more community friendly.
+
+#### pes-events.json and device_driver_deprecation_data.json
+
+Both PES events and device driver deprecation data only contain data for RHEL in the upstream `leapp-repository` and we will not include any data unrelated to RHEL. If you find a bug in the data, you can open a bug in the [RHEL Jira](https://issues.redhat.com/) for the `leapp-repository` component.
+
+Before contributing, make sure your PR conforms to our {doc}`Coding guidelines<coding-guidelines>`
+ and {doc}`PR guidelines<pr-guidelines>`.
diff --git a/docs/source/contributing/index.rst b/docs/source/contributing/index.rst
@@ -0,0 +1,18 @@
+Contributing
+========================================================
+
+.. toctree::
+    :maxdepth: 4
+    :caption: Contents:
+    :glob:
+
+    coding-guidelines
+    pr-guidelines
+    community-upgrades
+
+.. Indices and tables
+.. ==================
+..
+.. * :ref:`genindex`
+.. * :ref:`modindex`
+.. * :ref:`search`
diff --git a/docs/source/contributing/pr-guidelines.md b/docs/source/contributing/pr-guidelines.md
@@ -0,0 +1,48 @@
+# Commits and pull requests (PRs)
+## PR description
+The description should contain information about all introduced changes:
+* What has been changed
+* How it has been changed
+* The reason for the change
+* How could people try/test the PR
+* Reference to a Jira ticket, Github issue, ... if applicable
+
+Good description provides all information for readers without the need to
+read the code. Note that reviewers can decline to review the PR with a poor
+description.
+
+## Commit messages
+When your pull-request is ready to be reviewed, every commit needs to include
+a title and a body continuing a description of the change --- what problem is
+being solved and how. The end of the commit body should contain Jira issue
+number (if applicable), GitHub issue that is being fixed, etc.:
+```
+  Commit title
+
+  Commit message body on multiple lines
+
+  Jira-ref: <ticket-number>
+```
+
+Note that good commit message should provide information in similar way like
+the PR description. Poorly written commit messages can block the merge of PR
+or proper review.
+
+## Granularity of commits
+The granularity of commits depends strongly on the problem being solved. However,
+a large number of small commits is typically undesired. If possible, aim a
+Git history such that commits can be reverted individually, without requiring reverting
+numerous other dependent commits in order to get the `main` branch into a working state.
+
+Note that commits fixing problems of other commits in the PR are expected to be
+squashed before the final review and merge of the PR. Using of `git commit --fixup ...`
+and `git commit --squash ...` commands can help you to prepare such commits
+properly in advance and make the rebase later easier using `git rebase -i --autosquash`.
+We suggest you to get familiar with these commands as it can make your work really
+easier. Note that when you are starting to get higher number of such fixing commits
+in your PR, it's good practice to use the rebase more often. High numbers of such
+commits could make the final rebase more tricky in the end. So your PR should not
+have more than 15 commits at any time.
+
+## Create a separate git branch for your changes
+TBD
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -21,7 +21,7 @@ providing Red Hat Enterprise Linux in-place upgrade functionality.
     upgrade-architecture-and-workflow/index
     configuring-ipu/index
     libraries-and-api/index
-    contrib-and-devel-guidelines
+    contributing/index
     faq
 
 .. Indices and tables
