On Thu, May 07, 2020 at 07:34:13PM -0000, GitLab Bridge on behalf of jeremycline wrote: > From: Jeremy Cline <jcline@xxxxxxxxxx> > > 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@xxxxxxxxxx> > --- > 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@xxxxxxxxxx:<your gitlab name>/kernel-ark.git && cd kernel-ark > + git remote add -f upstream git@xxxxxxxxxx: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_set_up_Mock.3F > + > + > +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@xxxxxxxxxx> > + > +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@xxxxxxxxxx/ > + > +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. > -- > 2.26.2 Acked-by: Herton R. Krzesinski <herton@xxxxxxxxxx> -- []'s Herton _______________________________________________ kernel mailing list -- kernel@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe send an email to kernel-leave@xxxxxxxxxxxxxxxxxxxxxxx Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/kernel@xxxxxxxxxxxxxxxxxxxxxxx
