From 1dfcefcddd8b1cb898c33d759a0521bd6714edf5 Mon Sep 17 00:00:00 2001 From: Neal Gompa Date: Feb 28 2024 17:57:01 +0000 Subject: docs/contributing/kernel: Revise for the ARK-derived Hyperscale kernel We now build our kernel based on ARK, so the documentation has been updated to reflect the policies oriented around this. --- diff --git a/docs/contributing/kernel.md b/docs/contributing/kernel.md index 2511629..2d0e04d 100644 --- a/docs/contributing/kernel.md +++ b/docs/contributing/kernel.md @@ -1,14 +1,16 @@ -The Hyperscale SIG maintains a kernel in the [experimental repository](/hyperscale/repositories/experimental/#kernel). This kernel is based on the [CentOS Stream 9 kernel](https://gitlab.com/redhat/centos-stream/rpms/kernel/-/commits/c9s) and tries to follow it as closely as possible, while enabling additional features such as [btrfs](https://btrfs.wiki.kernel.org/index.php/Main_Page) and [Kernel Live Patching](https://www.kernel.org/doc/html/latest/livepatch/livepatch.html). In turn, the CentOS Stream 9 kernel is based on the [upstream RHEL 9 kernel sources](https://gitlab.com/redhat/centos-stream/src/kernel/centos-stream-9), which is where the RHEL 9 kernel is developed and maintained. +The Hyperscale SIG maintains a kernel in the [experimental repository](/hyperscale/repositories/experimental/#kernel). This kernel is based on the [Fedora kernel](https://src.fedoraproject.org/rpms/kernel) with a RHEL-ish configuration and tries to follow it as closely as possible, while enabling additional features such as [btrfs](https://btrfs.wiki.kernel.org/index.php/Main_Page) and [Kernel Live Patching](https://www.kernel.org/doc/html/latest/livepatch/livepatch.html). In turn, the kernel is based on the [upstream ARK sources](https://gitlab.com/cki-project/kernel-ark), which is where the Fedora kernel and future RHEL kernels are developed and released. -The Hyperscale kernel is built for both CentOS Stream 8 and CentOS Stream 9 from the same sources (meaning, we effectively ship a backport of the CentOS Stream 9 kernel for CentOS Stream 8). +The Hyperscale kernel is built for CentOS Stream 9 and eventually CentOS Stream 10 from the same sources (meaning, we effectively ship a backport of the Fedora kernel for CentOS Stream 9 and eventually CentOS Stream 10). # Contributing to the Hyperscale kernel -In general, the best way to contribute to the Hyperscale kernel build is to contribute to these upstream RHEL kernel sources. As a matter of policy, all of the patches we backport for the Hyperscale build of the kernel are first merged to [redhat/centos-stream/src/kernel/centos-stream-9](https://gitlab.com/redhat/centos-stream/src/kernel/centos-stream-9), which is the GitLab repo where the RHEL kernel is developed and maintained. This allows us to leverage the testing and maintenance by the RHEL kernel team and share efforts with the broader CentOS community that also contribute to the kernel. +In general, the best way to contribute to the Hyperscale kernel build is to contribute to the upstream Linux kernel sources. This follows the [Linux Kernel contribution process](https://docs.kernel.org/process/submitting-patches.html). + +As a matter of policy, all of the patches we backport for the Hyperscale build of the kernel are first merged to [cki-project/kernel-ark](https://gitlab.com/cki-project/kernal-ark), which is the GitLab repo where the Fedora kernel is developed and maintained. This allows us to leverage the testing and maintenance by the Red Hat kernel teams and share efforts with the broader community that also contribute to the kernel. We try to maintain as few patches as possible for each release, but we are open to including new features or bug fixes that are not yet available. We follow the practices [documented by the RHEL kernel team](https://redhat.gitlab.io/centos-stream/src/kernel/documentation/). -# Contributing to the RHEL 9 kernel sources +# Contributing to the ARK kernel sources * Get a Fedora account if you don't have one already. * Make sure to follow [this part](https://docs.fedoraproject.org/en-US/package-maintainers/Joining_the_Package_Maintainers/#install_the_developer_client_tools) @@ -18,34 +20,32 @@ We try to maintain as few patches as possible for each release, but we are open * Make sure the email address you use for Git commits is attached to your GitLab.com account. * Set your GitLab.com account username in your Fedora account. * Set your Red Hat Bugzilla account and make sure your Fedora account email address matches your Bugzilla account email address. -* Install [`git-backport`](https://gitlab.com/redhat/centos-stream/src/kernel/tools/-/raw/main/git-backport) into `~/.local/bin`. -* Fork [redhat/centos-stream/src/kernel/centos-stream-9](https://gitlab.com/redhat/centos-stream/src/kernel/centos-stream-9). -* In your local clone of your fork, add [redhat/centos-stream/src/kernel/centos-stream-9](https://gitlab.com/redhat/centos-stream/src/kernel/centos-stream-9) as a remote by the name `upstream`. +* Fork [cki-project/kernel-ark](https://gitlab.com/cki-project/kernel-ark). +* In your local clone of your fork, add [cki-project/kernel-ark](https://gitlab.com/cki-project/kernel-ark) as a remote by the name `upstream`. * In your local clone of your fork, add [torvalds/linux](https://github.com/torvalds/linux) as a remote by the name `mainline`. * Run `git fetch --all` to fetch all the refs from all the remotes. -* Create a new branch based on `upstream/main` for the patches to be applied: `git checkout --no-track -b upstream/main` -* Generate a list of commits to backport and save it to a file to use with `git-backport`. - * For example, for backporting zstd from v5.16, do: `git log --pretty=oneline v5.14..v5.16 lib/zstd | tac > git-backport-zstd-v5.16-patchset` -* [Create a bug for the RHEL kernel for your backport](https://bugzilla.redhat.com/enter_bug.cgi?product=Red%20Hat%20Enterprise%20Linux%209&version=CentOS%20Stream&component=kernel). - * Note: the link above might not select `kernel` as a component for you automatically. If it doesn't, just do so manually and select the correct subcomponent when the menu shows up. - * As an example, here's [the one done for the zstd backport from v5.16](http://bugzilla.redhat.com/2034834). -* Use `git-backport` to generate the patch set to apply as commits: `git-backport -a -b -d $PWD/backport-stage-diffs/ -f ` -* Use `git am` to apply the patch set: `git am $PWD/backport-stage-diffs/` +* Create a new branch based on `upstream/os-build` (next) or `upstream/fedora-X.Y` (current kernel series) for the patches to be applied. + * For example, for branching from `fedora-6.7`, do: `git checkout --no-track -b upstream/fedora-6.7` +* Generate a list of commits to backport and use `git-cherry-pick`. + * For example, for backporting zstd from v6.8 to v6.7, do: `git rev-list --reverse v6.7..v6.8 -- lib/zstd | git cherry-pick -n --stdin` * Push your branch to your fork on GitLab.com -* Open a merge request (MR) against [redhat/centos-stream/src/kernel/centos-stream-9](https://gitlab.com/redhat/centos-stream/src/kernel/centos-stream-9) with your change. - * In the MR description, add a `Signed-off-by` statement matching the ones in your commits. - * Tag `@Conan_Kudo` and `@dcavalca` to notify for reviews. - * As an example, here's [the MR done for the zstd backport from v5.16](https://gitlab.com/redhat/centos-stream/src/kernel/centos-stream-9/-/merge_requests/292). -* Once merged and the RHEL kernel folks make a release, one of the Hyperscale kernel maintainers will update the RPM spec and publish a new version of the kernel for Hyperscale with the patches included. +* Open a merge request (MR) against [cki-project/kernel-ark](https://gitlab.com/cki-project/kernel-ark) with your change. + * Tag `@jforbes`, `@Conan_Kudo` and `@dcavalca` to notify for reviews. +* Once merged and the Fedora kernel folks make a release, one of the Hyperscale kernel maintainers will update the RPM spec and publish a new version of the kernel for Hyperscale with the patches included. + +# Building the ARK or Hyperscale kernels + +The kernel package is maintained with the packaging data merged in with the source tree. This is commonly known as a "merged source" or "source-git" tree. Even so, the kernel package is special and requires a special process to build. -# Contributing to the RHEL 8 kernel sources +Being able to build the kernel is useful for testing patches you wish to contribute or if you want to make your own builds for personal use. -The same contribution process applies to the RHEL 8 kernel, with a few differences: +* Once in the root of the tree and you've made your changes, generate the changelog commit using `make dist-release-finish` + * For example, to make a build with `0.test.1` release, run `make dist-release-finish DISTLOCALVERSION="0.test.1" SNAPSHOT="0" BUILD="0"` +* Generate the git tag using `make dist-release-tag` + * For example, to make a build with `0.test.1` release, run `make dist-release-tag DISTLOCALVERSION="0.test.1" SNAPSHOT="0" BUILD="0"` +* Generate the SRPM using `make dist-srpm` + * For example, to make a SRPM with `0.test.1` release for CentOS Stream 9, run `make dist-srpm DISTLOCALVERSION="0.test.1" SNAPSHOT=0 BUILD="0" DIST=".el9"` -* you will want to fork [redhat/centos-stream/src/kernel/centos-stream-8](https://gitlab.com/redhat/centos-stream/src/kernel/centos-stream-8) and use it as your `upstream` -* you will want to [file a bug](https://bugzilla.redhat.com/enter_bug.cgi?product=Red%20Hat%20Enterprise%20Linux%208&version=CentOS%20Stream&component=kernel) against the kernel component for RHEL 8 -* to build the kernel locally, the easiest way is to use [Packit](https://packit.dev) - * run `packit srpm` to generate a source RPM - * run `mock -r centos-stream-8-x86_64 /path/to/the/src.rpm` to build the kernel from the generated source RPM +Once you have the generated SRPM, you can build it with `mock` like normal. -Note that changes contributed to the stock RHEL 8 kernel do not directly impact the Hyperscale kernel build, as that is based off the RHEL 9 kernel. They are however relevant for packages built in our [main repository](/hyperscale/repositories/main), as those are designed to run on a stock system. +If you're building off the `os-build` branch (or a branch derived from it), you will want to drop `SNAPSHOT="0"` from the arguments passed to `make`.