Submitting Contributions

Thanks for considering contributing to the Fedora and Always Ready kernels, we really appreciate it! Before you get started, please familiarize yourself with the general Fedora kernel policies.

These guides assume you’ve completed the Quick Start guide and are familiar with the Repository Layout.

All contributions must be constructed against the os-build branch which contains the configs for Fedora and ARK builds, and the kernel patches for Fedora and ARK.

Documentation

Contributions to the documentation are always welcome. This documentation is written with Sphinx. Your distribution should provide a Sphinx package, or you can set up an environment and build the documentation as HTML with:

python3 -m venv ~/.virtualenvs/ark-docs
source ~/.virtualenvs/ark-docs/bin/activate
pip install Sphinx
cd redhat/docs
make html

Your documentation changes should build in Sphinx without warnings and this is enforced by CI. You can check your changes locally with:

make SPHINXOPTS="-W" html

Reporting Kernel Bugs

Fedora bugs are only tracked in Red Hat’s Bugzilla instance. Fedora kernel bugs can be filed at https://bugzilla.redhat.com/ under Product “Fedora”, Component “kernel” and specifying the Version “rawhide”. Please try to be as detailed as possible when reporting a bug. The more detailed you are, the more likely it is that your bug will be resolved.

“Rawhide” is the name given to the current development version of Fedora Linux. If the kernel bug you’re reporting isn’t against the development version, then select the appropriate Fedora version (e.g., 38, 39, 40, etc.) instead of selecting “rawhide”.

Reporting ARK Project Issues

To report a problem with the kernel-ark project itself use the project issue tracker in GitLab at https://gitlab.com/cki-project/kernel-ark/-/issues and select the “New Issue” button.

An issue could be, for example, an infrastructure issue with merge request CI pipelines, a bug related to the RPM Spec file, a bug in the features and functionality maintained in the redhat directory, or it could be used to propose new ideas you may have for kernel-ark. The only type of issue that should not be reported here are kernel bugs. As noted above, please open a Bugzilla to track any kernel bugs that you find.

Patches

Quick start:

  1. git fetch orgin

  2. git checkout -b my-build-change origin/os-build

  3. Make a change to a file.

  4. Add your changes with git add -A.

  5. Commit your changes and write a nice commit message that explains the change: git commit -s.

  6. Open a merge request. You can do so via the web UI, or directly from a git push with git push -o merge_request.create -u <your-remote> my-build-change (defaults to target branch os-build). Refer to the push options documentation for more details.

Configuration Changes

Each configuration option for the kernel is placed in its own file inside the redhat/configs/<flavor>/ directory.

Each file must be named after the configuration option it contains.

To disable a particular setting, the file must contain # CONFIG_TOWEL is not set rather than CONFIG_TOWEL=n where CONFIG_TOWEL is replaced with the actual configuration option.

The directory is hierarchical by architecture families. The top level is generic configurations that apply across most architectures. Within that, there are directories like arm, powerpc, and x86 where architecture specific configurations are placed. Settings in these architecture-specific directories override any duplicate settings in the more generic directories. Configurations that are specific to a particular architecture should be placed in that architecture’s directory rather in the generic directory.

Configuration changes in the rhel directory requires review from Red Hat kernel developers, where-as the configurations in fedora can be changed with the approval of the Fedora kernel maintainers. The common directory is for changes common to both rhel and fedora and will be populated by a bot that periodically looks in both rhel and fedora for common changes.

Makefile changes

Guidelines for makefile target and variable changes are found in the Makefile Guidelines doc.

Commit messages

Each commit you make should contain a detailed description of why the change is necessary. For example, if the commit enables or disables a configuration option, explain exactly why the change is necessary. If there is a Bugzilla bug relating to the change, please include a reference to it using the format Bugzilla: <url>. For example:

Enable CONFIG_TOWEL so kernels never panic

Since the beginning the kernel has panicked. This has made a lot of people very
angry and has widely been regarded as a bad move. This new configuration option
solves all the kernel's problems and now it never panics.

Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1234567890
Signed-off-by: Jeremy Cline <jcline@redhat.com>

Kernel code patches should be submitted upstream prior to being sent for inclusion in Fedora. The commit message for the patch should be the same as upstream, except for the addition of a few tags the message.

Upstream Status

Each commit should contain an Upstream Status tag to indicate where the patch can be found. Some examples:

A patch that’s been sent upstream, but is not yet in a sub-maintainer’s tree should link to the email:

Upstream Status: https://lore.kernel.org/lkml/20200220151738.1492852-1-jcline@redhat.com/

A patch that’s been accepted into an upstream maintainer’s tree should reference the tree and should also include the upstream commit in the format used by git cherry-pick -x:

Upstream Status: netdev/net-next.git
(cherry picked from commit aed145ccb4918b8b6f7855be9dc6067bd48e4124)

If the tree isn’t hosted on kernel.org, Upstream Status should link to it.

Finally, a downstream-only patch should be marked:

Upstream Status: RHEL only

Bugzilla

As with configuration and build script changes, if there is a Bugzilla bug relating to the kernel commit, please include a reference to it using the format Bugzilla: <url>.

Continuous Integration

Tests are run on each merge request to ensure it does not introduce regressions. The test definitions are located at https://gitlab.com/cki-project/kernel-ark-ci. Since both main development branches need similar tests, the branches within this repository reference the CI definition there so they only need to be maintained in a single place.

Licensing

Your commit messages must include a Signed-off-by tag with your name and e-mail address, indicating that you agree to the Developer Certificate of Origin version 1.1:

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

Use git commit -s to add the Signed-off-by tag.