[OS-BUILD PATCHv2] redhat/configs/README: Update the README - kernel - Fedora mailing-lists

1 Jun 2022

From: Prarit Bhargava prarit@redhat.com
redhat/configs/README: Update the README
The information in this file was a bit out-of-date and needed a refresh.
Update the README.
Signed-off-by: Prarit Bhargava prarit@redhat.com

diff --git a/redhat/configs/README b/redhat/configs/README
index blahblah..blahblah 100644
--- a/redhat/configs/README
+++ b/redhat/configs/README
@@ -1,63 +1,84 @@
-Red Hat Enterprise Linux Always Ready config option scheme
-------------------------------------------------------
+kernel-ark CONFIG option scheme
+-------------------------------
-Historically, the RHEL kernel is forked from a Fedora kernel.
-Today, the Always Ready Kernel (ARK) is constantly rebased as new kernel
-releases come out. New configuration options are reviewed and set
-with each release.
+The kernel-ark repository contains both Fedora and ark (aka "RHEL next")
+CONFIGS.  This repository is constantly rebased as the upstream kernel releases
+new kernel version. New configuration options are reviewed and set with each
+release, typically during the -rc1 to -rc3 releases.
-The config options are split out into a hierarchical
-tree structure, with one file per config option at each level of the
-hierarchy. The config options are merged and properly layered according to
-the file "priority" in the same directory as this README to generate the
-final kernel-$VERSION-<arch>-<variant>.config files we need for building the
-actual kernels.
+The kernel-ark configs are broken out into ark, fedora, and common directories
+in which each directory provides a heirarchical layout of the configs starting
+with generic/CONFIG_* and debug/CONFIG_*, then generic/<arch>/CONFIG_* and
+generic/<arch>/<variant>/CONFIG_*, debug/<arch>/CONFIG_*, etc.  Users should be
+aware that it may not necessarily be the case that architecture support is
+consistent between ark and fedora.
+
+The config options are merged and properly layered according to the priority.*
+files in the same directory as this README to generate the final
+kernel-$VERSION-<arch>-<variant>.config files we need for building the actual
+kernels.  For example, the ark variant priorities are found in priority.rhel,
+and in the case of x86_64 architecture, the specific information required is,
+
+ORDER=common ark pending-ark custom-overrides
+
+and
+
+x86_64=generic:generic-x86:generic-x86-x86_64
+
+This indicates that for the x86_64 variant, the order that of inheritance would be:
+
+custom-overrides/generic/x86/x86_64	(highest override priority)
+custom-overrides/generic/x86
+custom-overrides/generic
+pending-ark/generic/x86/x86_64
+pending-ark/generic/x86
+pending-ark/generic
+ark/generic/x86/x86_64
+ark/generic/x86
+ark/generic
+common/generic/x86/x86_64
+common/generic/x86
+common/generic				(lowest override priority)
+
+A text-based graphical representation of a specific CONFIG can be viewed
+by using the evaluate_configs utility in this directory.
+
+	ex) evaluate_configs -p priority.rhel -c CONFIG_PCI
+
+Directory Layout
+----------------
The configuration is broken down into several directories:
-ark - This contains all configuration options that have been fully
-reviewed by kernel developers and are suitable for inclusion at branch time.
-
-pending-common - This directory contains all configuration options that have
-not yet been fully reviewed for inclusion. Because of the rate at which
-kernel options come out, we can't guarantee everything has been reviewed
-by the time a build needs to happen. In the interest of letting the build
-proceed for other testing, configuration options are staged in the
-pending directory. It is expected that this directory will be empty
-at branch time.
-
-In each directory (ark etc.), we have generic/CONFIG_* and debug/CONFIG_*, then
-generic/<arch>/CONFIG_* and generic/<arch>/<variant>/CONFIG_*, as well as
-debug/<arch>/CONFIG_*. While this may seem overly complex compared with
-past RHEL kernel config setups at first glance, its actually quite
-straight-forward and should be less error-prone. There's no potential
-for configuration options getting out of order or conflicts when changing
-adjacent configuraiton options.
-
-pending-fedora - This directory contains configuration options that have not
-been reviewed by Fedora kernel maintainers. Since the Fedora kernel turns on
-more configuration options than ARK, there are often settings that are not set
-to default in pending-common. These settings are moved to the fedora/
-configuration directory after community review. Options are populated with
-"make FLAVOR=fedora dist-commit-configs".
-
-custom-overrides - This directory contains an empty set of the generic and debug
-arch-specific directory tree. Any config option set here is applied last and
-therefore will override anything set in the ark, fedora, or pending directories.
-This allows users to easily override a config option without altering the
-standard directories. Users can even maintain their own branch with a full set
-of custom configuration options that can be easily be rebased on top of
-os-build without worrying about conflicts.
-
-All the configuration options for each arch and variant can be found
-in the "priority" file.
-
-If you want to make a change that applies to all kernels, debug and
-non-debug alike, add a config option file under ark/generic/. If it should
-only apply to all debug kernels, add it under ark/debug/. Arch-specific
-options go under ark/generic/<arch>/ and so on. Each layer's individual config
-option files are concatenated together with all other options at the same
-level, then stacked atop the lower layers until reaching the highest
-precedence layer for the given config option.
-
-Send any questions, comments or concerns to rhkernel-list@redhat.com.
+ark - contains all configuration options that have been reviewed by kernel
+developers for the ark kernel.
+
+common - contains all configuration options that are common between the fedora
+and ark directories.  In other words, these config settings apply to both
+fedora and ark.
+
+custom-overrides - contains an empty set of the generic and debug arch-specific
+directory tree. Any config option set here is applied last and therefore will
+override anything set in the ark, fedora, or pending directories.  This feature
+was added to assist users executing custom builds to easily override a config
+option without altering the standard directories. Users can even maintain their
+own branch with a full set of custom configuration options that can be easily
+be rebased on top of os-build without worrying about conflicts.
+
+fedora - contains all configuration options that have been reviewed by kernel
+developers for the fedora kernel.
+
+pending-[ark][common][fedora] - These directories contain configuration options
+that have not yet been fully reviewed for inclusion for ark, fedora, and both
+(common) kernels.  Due to the rate at which kernel options come out, the kernel
+maintainers cannot guarantee reviews of configs in these directories by the
+time a build occurs.  In the interest of letting the build proceed for other
+testing, configuration options are staged in these pending directories.
+
+As pending-* configs are reviewed, they are moved into the matching non-pending
+directory (ie, pending-ark -> ark, etc.) and it is expected that these
+directories will be empty at branch time.
+
+Config files can be populated using the pending-* directories by using the
+"FLAVOR" Makefile variable; for example to build the fedora configs, users can
+execute "make FLAVOR=fedora dist-commit-configs".
--
https://gitlab.com/cki-project/kernel-ark/-/merge_requests/1841

    