======================== 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 :ref:`quick-start` guide and are familiar with the :ref:`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 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//`` 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 :ref:`makefile-changes` 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: ``. 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 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: ``. 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.