From 9f2c312759649feed66dfa7ed197818604dcfd76 Mon Sep 17 00:00:00 2001 From: Neal Gompa Date: Jan 20 2022 00:20:05 +0000 Subject: docs/internal: Initial kernel contribution/maintenance documentation This documentation is based on the experience doing a few contributions to the RHEL kernel. --- diff --git a/docs/internal/kernel.md b/docs/internal/kernel.md new file mode 100644 index 0000000..6b926f3 --- /dev/null +++ b/docs/internal/kernel.md @@ -0,0 +1,90 @@ +# About the kernel in Hyperscale + +We try to follow the [kernel build from CentOS Stream 9](https://gitlab.com/redhat/centos-stream/rpms/kernel/-/commits/c9s) as closely as possible. + +# CI/CD + +Links can be found [on the CI/CD page](ci.md). + +# Contributing to the Hyperscale kernel code + +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), +a Git 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. + +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/). + +Steps: + +* 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) + and set up your `~/.fedora.upn` to tell our tooling your FAS username if it differs from your Unix name. +* Get a GitLab.com account if you don't have one already. + * Make sure your display name matches your actual name used in Git commits. + * 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`. +* 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/` +* 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. + +# Contributing to the RPM spec + +Not yet available + +[kernel Hyperscale RPM sources](https://git.centos.org/rpms/kernel/tree/c9s-sig-hyperscale) + +# Build Commands + +For CBS you will need to be [onboarded to the SIG](onboarding.md). + +From inside the fork of the [kernel Hyperscale RPM sources](https://git.centos.org/rpms/kernel/tree/c9s-sig-hyperscale) repo: + +``` +# Local build with mock; You can skip these steps and use cbs directly +mock -r centos-stream-9-x86_64 -D '%dist .hsx.el9' --sources SOURCES --spec SPECS/*.spec + +# Create src.rpm for CBS +rpmbuild --define "%_topdir $PWD" --define "%dist .hsx.el9" -bs SPECS/kernel.spec + +# CBS scratch builds +cbs build --scratch hyperscale9s-packages-experimental-el9s +``` + +Once the specfile changes are pushed you can do a real build: + +``` +# CBS builds for CentOS Stream 8 +git checkout c8s-sig-hyperscale +cbs build hyperscale8s-packages-experimental-el8 "git+https://git.centos.org/rpms/kernel.git#$(git rev-parse HEAD)" + +# CBS builds for CentOS Stream 9 +git checkout c9s-sig-hyperscale +cbs build hyperscale9s-packages-experimental-el9s "git+https://git.centos.org/rpms/kernel.git#$(git rev-parse HEAD)" + +# Tag it for testing +cbs tag-build hyperscale8s-packages-experimental-testing kernel-.hsx.el8 +cbs tag-build hyperscale9s-packages-experimental-testing kernel-.hsx.el9 + +# Tag for release; This will let it go to the mirrors +cbs tag-build hyperscale8s-packages-experimental-release kernel-.hsx.el8 +cbs tag-build hyperscale9s-packages-experimental-release kernel-.hsx.el9 +``` diff --git a/mkdocs.yml b/mkdocs.yml index c0d73a3..7edb00f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,6 +24,7 @@ nav: - Versioning policy: internal/versioning_policy.md - CI/CD: internal/ci.md - Systemd: internal/systemd.md + - Kernel: internal/kernel.md theme: name: material