From: Jeremy Cline jcline@redhat.com

Although the GitLab wiki is pretty nice for getting started, it doesn't offer a great way for folks to contribute or provide reviews for changes. Convert the current Wiki to RST and build it with Sphinx. This should be nearly identical to the content of the wiki with the exception of a new section on contributing to the documentation.

When this is accepted, a new CI job can be added to automatically lint, build, and host the Sphinx documentation on GitLab pages[0].

[0] https://docs.gitlab.com/ee/user/project/pages/

Signed-off-by: Jeremy Cline jcline@redhat.com --- redhat/docs/.gitignore | 1 + redhat/docs/Makefile | 20 ++ redhat/docs/conf.py | 47 +++++ redhat/docs/index.rst | 110 +++++++++++ redhat/docs/maintaining.rst | 229 ++++++++++++++++++++++ redhat/docs/repository-layout.rst | 171 +++++++++++++++++ redhat/docs/submitting-contributions.rst | 235 +++++++++++++++++++++++ 7 files changed, 813 insertions(+) create mode 100644 redhat/docs/.gitignore create mode 100644 redhat/docs/Makefile create mode 100644 redhat/docs/conf.py create mode 100644 redhat/docs/index.rst create mode 100644 redhat/docs/maintaining.rst create mode 100644 redhat/docs/repository-layout.rst create mode 100644 redhat/docs/submitting-contributions.rst

diff --git a/redhat/docs/.gitignore b/redhat/docs/.gitignore new file mode 100644 index 000000000000..69fa449dd96e --- /dev/null +++ b/redhat/docs/.gitignore @@ -0,0 +1 @@ +_build/ diff --git a/redhat/docs/Makefile b/redhat/docs/Makefile new file mode 100644 index 000000000000..d4bb2cbb9edd --- /dev/null +++ b/redhat/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/redhat/docs/conf.py b/redhat/docs/conf.py new file mode 100644 index 000000000000..b5e60902cd65 --- /dev/null +++ b/redhat/docs/conf.py @@ -0,0 +1,47 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + + +# -- Project information ----------------------------------------------------- + +project = "Fedora/ARK Kernel" +copyright = "2020, Red Hat, Inc" +author = "Red Hat, Fedora Community" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "alabaster" + +html_theme_options = { + "page_width": "1100px", + "show_related": True, + "sidebar_collapse": True, +} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] diff --git a/redhat/docs/index.rst b/redhat/docs/index.rst new file mode 100644 index 000000000000..7d13aec5940f --- /dev/null +++ b/redhat/docs/index.rst @@ -0,0 +1,110 @@ +.. Fedora Kernel and ARK Documentation documentation master file, created by + sphinx-quickstart on Thu May 7 14:44:56 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +================= +Fedora/ARK Kernel +================= + +This documentation covers setting up a development environment, the repository +layout, and the general contribution workflow. + +.. _quick-start: + +Quick Start +=========== + +Setup +----- + +To start with you need to: + +1. Make a `GitLab account`_ if you do not already have one. +2. `Fork the ARK tree`_. Wait patiently for this to complete. +3. Setup `Koji`_ and `Mock`_ if necessary. + +Once GitLab finishes forking the repository (this can take a while): + +:: + + # Cloning with these URLs requires that you have an SSH key registered with GitLab + # If you've not yet set up keys, you can clone with with: + # git clone https://gitlab.com/<your gitlab name>/kernel-ark.git && cd kernel-ark + # git remote add -f upstream https://gitlab.com/cki-project/kernel-ark.git + git clone git@gitlab.com:<your gitlab name>/kernel-ark.git && cd kernel-ark + git remote add -f upstream git@gitlab.com:cki-project/kernel-ark.git + + # Install build dependencies + sudo dnf install -y make gcc flex bison bzip2 rpm-build + git checkout upstream/ark-latest + # If you're on Fedora, you need to run: + # ln -s /usr/bin/python3 /usr/libexec/platform-python + make rh-srpm + sudo dnf builddep -y redhat/rpm/SPECS/kernel.spec + + +Building an SRPM +---------------- + +The configuration and build scripts are in the ``os-build`` branch and +are regularly updated to work with Linus's master branch. To build an +SRPM, start by checking out the source tree you'd like to build. In this +example, we'll assume that is Linus's master branch, but it could just +as easily be Fedora's ``ark-patches`` branch (Linus's tree + Fedora +patches) , a sub-system maintainer's tree, or your own creation. + +:: + + git checkout linus/master + git merge -m "Merge branch 'os-build'" os-build + # Fedora carries a patch to alter this setting, so we need to change the configuration to build a vanilla tree. + sed -i 's/=13/=11/g' redhat/configs/fedora/generic/arm/aarch64/CONFIG_FORCE_MAX_ZONEORDER + # If you're targeting RHEL and have brew/rhpkg installed, use "make DIST=.elrdy rh-srpm" instead + make rh-srpm + +You can now build the SRPM however you like: + +:: + + # Build the SRPM locally + mock redhat/rpm/SRPMS/kernel*src.rpm + # Build the SRPM in Fedora's Koji + koji build --scratch rawhide redhat/rpm/SRPMS/kernel*src.rpm + +Want to add a patch? Just git-cherry-pick it or apply it with git-am and +re-run ``make rh-srpm``. Change configurations in ``redhat/configs/`` +(consult the repository layout for details on this). + + +Contributor Guide +================= + +.. toctree:: + :maxdepth: 2 + + repository-layout + submitting-contributions + + +Maintainer Guide +================ + +.. toctree:: + :maxdepth: 2 + + maintaining + + +.. _GitLab account: https://gitlab.com/users/sign_in#register-pane +.. _Fork the ARK tree: https://gitlab.com/cki-project/kernel-ark/-/forks/new +.. _Koji: https://fedoraproject.org/wiki/Using_the_Koji_build_system#Koji_Setup +.. _Mock: https://fedoraproject.org/wiki/Using_Mock_to_test_package_builds#How_do_I_se... + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/redhat/docs/maintaining.rst b/redhat/docs/maintaining.rst new file mode 100644 index 000000000000..3cfd8b6d2904 --- /dev/null +++ b/redhat/docs/maintaining.rst @@ -0,0 +1,229 @@ +=========== +Maintenance +=========== + +This guide covers common maintenance tasks and is primarily aimed at +kernel maintainers. It assumes you have write access to +`https://gitlab.com/cki-project/kernel-ark.git https://gitlab.com/cki-project/kernel-ark.git`__ +and the remote in your clone is called "upstream", as set up in the +quick start guide. + +The repository is used for both the Fedora kernel and the RHEL Always +Ready kernel (ARK). Thus, it contains two sets of configurations. + +Every release requires the maintainer to: + +1. Rebase the downstream kernel patches +2. Update the configuration +3. Create a release branch and/or tag + +Once that is done, the result can be imported into a dist-git repository +and built in Koji. + +There is a script to automate the entire process which is run nightly by +CI/CD. You can run it locally: + +:: + + # Ensure we've got a clean check out for all the branches we're about to use + git checkout master && git pull + git checkout ark-patches && git reset --hard upstream/ark-patches + git checkout internal && git pull + + # Create a release based on "master", which tracks mainline + ./redhat/scripts/ci/ark-create-release.sh master + +The individual steps taken are described below for the curious. + +Rebasing Kernel Patches +----------------------- + +The downstream kernel patches are in a branch called ``ark-patches``. +This branch is regularly rebased onto Linus's master branch. + +The rebase consists of the following steps: + +1. Ensure your checkout is in a clean state: + +:: + + git checkout master + git reset --hard upstream/master + git checkout ark-patches + git reset --hard upstream/ark-patches + git checkout os-build + git reset --hard upstream/os-build + +2. Rebase the kernel patches onto master: + ``./redhat/scripts/ci/ark-rebase-patches.sh "master"``. If you'd like + for the script to drop patches that conflict and file issues on the + GitLab issue tracker, ensure the "REPORT_BUGS" environment variable + is set to something other than an empty string. + +3. If rebasing onto a tag, the script will create a branch for this + revision of the kernel patches. This is useful when comparing the + state of the patches between versions. Push this to the remote + repository with ``git push upstream ark/patches/<tag>``. + +4. If the patches required conflict resolution, update the remote with + ``git push -f upstream ark-patches``. If they didn't, there's no need + to update the branch as force pushing it breaks existing merge + requests against it. + +Common Problems +~~~~~~~~~~~~~~~ + +There are a few issues that can occur during the patch rebase. + +Patch Cannot Be Applied +^^^^^^^^^^^^^^^^^^^^^^^ + +Patches regularly fail to apply because upstream changed some code being +patched. When this occurs, if the fix is trivial, you can simply fix up +the patch during the ``git-rebase``. Otherwise, file an issue to fix the +patch and skip it during the rebase. + +Once a dropped patch has a fix, submit a merge request to +``ark-patches`` with the fixed-up patch. If you aren't confident you can +fix it yourself, try contacting the original author and ask them to fix +their patch. + +Patch Applies But Is Broken +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This problem occurs less frequently, but is also less straightforward to +detect and fix. A patch might cleanly apply, but an interface it uses +has changed in some way (e.g. a function got renamed). Ideally the +change causes the build to fail. + +Assuming you know how to fix the problem, use the following approach: + +1. Start a branch based of the latest ``ark-patches`` branch and fix the + problem as you see fit. +2. Commit the change, including a + ``Fixes: <short sha of commit in ark-patches it fixes>`` tag in the + commit, along with references to the upstream commit that introduced + the breaking change and any other details you see fit. If you + reference a commit that is not upstream (that is, any patch in + ark-patches) be sure to add a [x] reference and link to the commit so + email users can see the commit in question easily during review. +3. Submit a merge request against ``ark-patches`` +4. Once reviewed, merge the merge request. When rebasing + ``ark-patches``, squash the fix into the commit it fixes so that the + patches in ``ark-patches`` continue to be self-contained. + +An example of this is +`https://gitlab.com/cki-project/kernel-ark/merge_requests/90 https://gitlab.com/cki-project/kernel-ark/merge_requests/90`__. + +Configuration +------------- + +Once the patches are rebased, update the configuration branch: + +1. Set defaults for any new configuration files: + +:: + + git checkout os-build + ./redhat/scripts/ci/ark-update-configs.sh "master" + +2. Open a merge request for each branch created in step 1 (if any): + +:: + + git checkout os-build + if git branch | grep configs/"$(date +%F)"; then + git push upstream os-build + for branch in $(git branch | grep configs/"$(date +%F)"); do + git push -o merge_request.create -o merge_request.target=os-build -o merge_request.remove_source_branch upstream "$branch" + done + fi + +Release branch +-------------- + +Once the kernel patches and configuration have been updated for the new +release, it's time to create the release branch and/or tag. If this is a +snapshot build (i.e. master does not point to a tag), we only create a +tag. + +Snapshot Release +~~~~~~~~~~~~~~~~ + +:: + + git checkout -b build-branch ark-patches + git merge -m "Merge configuration and build scripts" os-build + # If there's a temporary fix you want in just this build, you can run git-cherry-pick here. + touch localversion + make rh-release + make rh-release-tag + git push upstream $(git describe) + git branch -D build-branch + +Upstream Release +~~~~~~~~~~~~~~~~ + +:: + + UPSTREAM_REF=<tag> + git checkout -b ark/"$UPSTREAM_REF" ark/patches/"$UPSTREAM_REF" + git merge -m "Merge configuration and build scripts" os-build + touch localversion + make rh-release + make rh-release-tag + git push $(git describe) ark/"$UPSTREAM_REF" ark/patches/"$UPSTREAM_REF" + git checkout ark-latest && git reset --hard ark/"$UPSTREAM_REF" && git push -f upstream ark-latest + +Building +-------- + +After a release branch has been prepared, it's time to build it. This +guide assumes you have Koji and/or Brew installed and properly +configured. It also assumes you've authenticated and have permissions to +build. + +Fedora +~~~~~~ + +This requires having fedpkg installed. + +From the release branch/tag, run: + +:: + + # Checks out the Fedora dist-git repository and copies everything from the source tree into it + # + # By default, this creates a directory in /tmp, but the location can be set with RHDISTGIT_TMP. + # If you already have a local clone of the Fedora dist-git repository, it can be used with RHDISTGIT_CACHE=<path-to-repo>. + # + # localversion sets the buildid, releases should have an empty build id + rm localversion + touch localversion + make rh-dist-git + + cd /tmp/RHEL*/kernel + git commit -a -s -F ../changelog + fedpkg push + fedpkg build + +ARK +~~~ + +This requires having rhpkg-sha512 installed and brew. + +From the release branch/tag, run: + +:: + + # localversion sets the buildid, releases should have an empty build id + rm localversion + touch localversion + make DIST=.elrdy rh-dist-git + cd /tmp/RHEL-8*/kernel + git commit -a -s -F ../changelog + git push + rhpkg tag -F ../changelog + git push origin $(git describe) + rhpkg build --target temp-ark-rhel-8-test --skip-nvr-check + diff --git a/redhat/docs/repository-layout.rst b/redhat/docs/repository-layout.rst new file mode 100644 index 000000000000..d9a0e110168c --- /dev/null +++ b/redhat/docs/repository-layout.rst @@ -0,0 +1,171 @@ +.. _repository-layout: + +================= +Repository Layout +================= + +The repository is based on the upstream Linux kernel tree. All branches +except master, though, are downstream-only. + +Branches +-------- + +master +~~~~~~ + +The master branch tracks `Linus's master +branch git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git`__ +(i.e. "mainline"). + +os-build +~~~~~~~~ + +The os-build branch is used for the kernel configuration and build +scripts. When new configuration options are needed or the build +requirements change, this is the branch to send merge requests to. When +a new release is made, this branch is merged into the release branch. +Configuration and build scripts can be found in the ``redhat/`` +directory. Refer to the Configuration section below for more details. + +ark-latest +~~~~~~~~~~ + +This branch points to the latest release branch. **This is not a +development branch, do not base merge requests off this branch.** + +ark-patches +~~~~~~~~~~~ + +**This branch is regularly rebased; do not rely on commit hashes in this +branch unless they are contained by a tag or release branch!** + +This branch tracks the latest version of the kernel patches for ARK and +Fedora. Patches for a particular release are available via the +``ark/patches/vX.Y[-rcN]`` branches. + +Release branches +~~~~~~~~~~~~~~~~ + +Each time the kernel is rebased, a set of branches is created to track +that release. + +.. _arkpatchesvxy-rcn: + +ark/patches/vX.Y[-rcN] +^^^^^^^^^^^^^^^^^^^^^^ + +Branches in this format (e.g. ``ark/patches/v5.4-rc1`` or +``ark/patches/v5.3``) contain the kernel patches ARK carries for that +particular kernel release. These are merged into the ``ark/vX.Y`` +release branches. + +.. _arkvxy-rcn: + +ark/vX.Y[-rcN] +^^^^^^^^^^^^^^ + +Branches in this format (e.g. ``ark/v5.4-rc1`` or ``ark/v5.3``) contain +the set of patches that were added on top of the upstream kernel release +along with the configuration and build scripts. They can be checked out +and built into RPMs. The ``master`` branch points to the latest version +of these branches. + +rhpatches +~~~~~~~~~ + +This branch is no longer used. Previously, it held the Red Hat patches +for the kernel as a quilt series and remains for historical reasons. +Patch history up to v5.4 is available in this branch. + +Tags +---- + +.. _vxy-rcn: + +vX.Y[-rcN] +~~~~~~~~~~ + +Tags in this format (e.g. ``v5.4-rc1`` or ``v5.3``) are the upstream +Linux kernel tags from Linus's tree. + +.. _kernel-xyz-ndist-and-kernel-xyz-0rcnyyyymmddgitshort-hashdist: + +kernel-X.Y.Z-N.<dist> and kernel-X.Y.Z-0.rcN.YYYYMMDDgit<short-hash>.<dist> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Tags in this format (e.g. ``kernel-5.4.0-1.elrdy``, +``kernel-5.6.0-1.fc33``, or +``kernel-5.6.0-0.rc5.20200314gitabcd1234.fc33``) map to the RPM +name-version-release tuple in the build system. These can be used to +check out the source tree used to build that RPM. Tags with the +``elrdy`` dist are Always Ready kernel releases and tags with the +``fcNN`` dist are Fedora kernels. + +The tags come in two varieties. The first is kernel builds based off an +upstream tag. ``kernel-5.4.0-1.elrdy`` and ``kernel-5.6.0-0.rc6.fc33`` +fall into this category. The second variety, which includes a date and +commit hash, is based off a snapshot of Linus's master branch for that +particular day. The git commit hash included in the release is the +commit in Linus's tree the build is based on, *not* the commit in the +Fedora source tree. + +Configuration +------------- + +The configuration layout is somewhat complicated. All configuration is +located on the ``os-build`` branch in ``redhat/configs/``. Inside this +directory there are a number of scripts used to automatically generate +complete configurations, along with a number of directories that contain +configuration snippets. At this time, there are three main configuration +directories: ``ark``, ``common``, and ``fedora``. ``ark`` and ``fedora`` +are configuration "flavors", while ``common`` is shared configuration +across flavors. + +A flavor is defined by: + +1. Adding the flavor name to ``redhat/configs/flavors`` on its own line. +2. Create a directory using your flavor name in ``redhat/configs/`` that + matches the layout of other flavors. +3. Defining a configuration priority by creating a file called + ``redhat/configs/priority.$flavorname``. This file needs to define a + number of bash variables that describe the priority of the various + configuration directories and should include the directory you + defined in step 2. + +common and common-pending +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``common`` directory contains configuration values that are shared +across all configuration "flavors". For a configuration to be in +``common``, it MUST be reviewed and approved by one or more Red Hat +subsystem maintainers since it affects ARK. A flavor's configurations +can override settings in ``common``, so it's not guaranteed settings in +common are the same across all flavors. It's simply a good place to set +common values across the flavors and use as a base for new flavors. + +``common-pending`` is where configuration options that have not been +reviewed are placed. Automation creates snippets for all new +configuration options exposed during a rebase of ARK in the +``pending-common`` directory, at which point subsystem maintainers +review the options and set them as appropriate before moving them into +``common``. + +New ARK configurations are placed in ``common-pending`` because it is +assumed that ARK generally has the most conservative settings, whereas +other flavors like Fedora will be (for the most part) a superset of the +ARK configuration. + +fedora and fedora-pending +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``fedora`` directory contains settings that have been reviewed by +Fedora kernel maintainers for the Fedora Rawhide kernel. + +Since Fedora tends to turn on more things than ARK, it's common for a +rebase to expose new configuration options that only apply to Fedora. +For this reason, Fedora has a ``pending-fedora`` directory as well. +``pending-fedora`` contains settings that are not exposed by the +``common`` configuration set and only apply to Fedora. It is, like +``pending-common``, populated automatically during a rebase. A Fedora +kernel maintain can review the settings at their leisure and move them +over to ``fedora`` as they do so. diff --git a/redhat/docs/submitting-contributions.rst b/redhat/docs/submitting-contributions.rst new file mode 100644 index 000000000000..cde7c454b7a2 --- /dev/null +++ b/redhat/docs/submitting-contributions.rst @@ -0,0 +1,235 @@ +======================== +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 https://docs.fedoraproject.org/en-US/quick-docs/kernel/overview/#_policies`__. + +These guides assume you've completed the :ref:`quick-start` guide +and are familiar with the :ref:`repository-layout`. + +There are two major types of contributions ARK accepts. The first is +kernel configuration options and build scripts, both of which live in +the ``os-build`` branch. The second are patches to the kernel itself, +which are in the ``ark-patches`` branch. + +Documentation +============= + +Contributions to the documentation are always welcome. This documentation is +written with `Sphinx https://www.sphinx-doc.org/`_. 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 + +Configuration, Build Scripts, and Specfile +========================================== + +Quick start: + +1. ``git fetch upstream`` +2. ``git checkout upstream/os-build && git checkout -b my-build-change`` +3. Make a change to a file or files in ``redhat/``. +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 https://docs.gitlab.com/ee/user/project/push_options.html`__ + 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 ``common`` and ``ark`` directories require +review from Red Hat kernel developers, where-as the configurations in +``fedora`` can be changed with the approval of the Fedora kernel +maintainers. + +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 Patches +============== + +To add or update a kernel patch carried for ARK, start a new branch +based on ``ark-patches``: + +1. ``git fetch upstream`` +2. ``git checkout -b my-kernel-patch upstream/ark-patches`` +3. Add commits any way you'd like (``git am``, ``git cherry-pick -x``, + etc). Patches are not likely to be accepted if they're not already on + their way upstream. +4. Open a merge request against ``ark-patches``. You can do so in the + web UI, or directly from a git push command: + ``git push -o merge_request.create -o merge_request.target=ark-patches -u <your-remote> my-kernel-patch``. + Refer to the `push + options https://docs.gitlab.com/ee/user/project/push_options.html`__ + documentation for more details. + +.. _commit-messages-1: + +Commit messages +--------------- + +Kernel 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>``. + +Changes with Kernel Patches and Configuration +============================================= + +It's common for a kernel patch to introduce a new configuration option. +When this occurs, you'll need to open two merge requests: + +1. A merge request against ``os-build`` with the configuration change. +2. A merge request against ``ark-patches`` with the kernel patches. + +Mark MR 1 as a Merge Request dependency of MR 2. When they've both been +reviewed the maintainer will queue them up to merge at the same time. + +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 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 https://developercertificate.org/`__ 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.