diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 66eb3be..2f35336 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -59,7 +59,7 @@ * xref:kernel/overview.adoc[Kernel] ** xref:kernel/troubleshooting.adoc[Troubleshooting] ** xref:kernel/build-custom-kernel.adoc[Building a Custom Kernel] - +** xref:kernel/howto-kernel-testday.adoc[Guide for Kernel Test Days] * Virtualization diff --git a/modules/ROOT/pages/kernel/howto-kernel-testday.adoc b/modules/ROOT/pages/kernel/howto-kernel-testday.adoc new file mode 100644 index 0000000..23554ae --- /dev/null +++ b/modules/ROOT/pages/kernel/howto-kernel-testday.adoc @@ -0,0 +1,117 @@ +Kernel Test Days +================ +Author Name +2019-04-08 +:description: A quick guide for Kernel Test Days. +:toc: +:compat-mode!: + +During *Kernel Test Days*, contributors are asked to run a _Kernel Regression Test_ which will help to detect and troubleshoot any issue with a new kernel version, before wider usage. +It consist in running a series of tests provided by the https://pagure.io/kernel-tests[Kernel Test Suite] + +The main goal of a Kernel Test Day is to test a new kernel on many different machines as possible, so every new Kernel Test Day is announced some days in advance with a https://fedoramagazine.org/[fedoramagazine] post. + +== What to do during Kernel Test Days + +The first thing to do is to get the right kernel version to test. +There are different ways to get the kernel and test it: + +=== Using a test day image + +During test days a dedicated wiki page will provide a link to download a *test day image* which is a live distro of Fedora with the kernel version to test already in it. +The test day image also contain the _test suite_, aka the scripts to test the kernel on your machine. +The downloaded .iso file must then be written in a bootable USB stick. + +TIP: Check https://docs.fedoraproject.org/en-US/quick-docs/creating-and-using-a-live-installation-image/#proc_creating-and-using-live-usb[this guide] for creating a bootable USB stick. + +You can then boot the live image and run the tests without worries of messing up with your OS. + +=== Using a Virtual Machine + +You can also install the required kernel version on a Virtual Machine running an up to date Fedora release and do the test in the VM. +In this case you can just add https://copr.fedorainfracloud.org/coprs/jforbes/kernel-stabilization/[this] *Copr repository* on the Fedora distro running in your VM. + +Once you added the repository,install the kernel to test: + + sudo dnf upgrade && sudo dnf install kernel-5.0.0-200.fc29.x86_64 + +* In the example above we install kernel-5.0.0-200 on fedora 29 with 64 bit architecture. +* Reboot and you are ready to test. + +=== Using Koji + +During kernel test days, the dedicated wiki page will provide a link to download the newly built kernel version to test, directly from koji builds. +This is recommended for secure boot users. + +IMPORTANT: *Disclaimer*: You could also install and test the new kernel on your Workstation/Server installation, on a bare metal machine, but make sure you have no important data on that installation, things might go wrong -- don't do this on your production machine! + +=== Lets prepare for testing (and earn a new Fedora Badge!) + +Before testing, you need to install some packages: + + sudo dnf install gcc git python-fedora keyutils libtirpc-devel + +* If you are using the _*test day image*_ you already have the kernel-test suite in the kernel-tests folder; enter the folder with + + cd /home/liveuser/kernel-tests + +* If you are not using the test day image you will need to clone the kernel-tests repo. +Use this command in terminal: + + git clone https://pagure.io/kernel-tests.git + +this will download the same folder that you find in the test day image, with the testing scripts. +When the download is finished, enter the kernel-tests folder: + + cd kernel-tests + +Once inside the kernel-tests folder, it’s time to edit some configuration files; first we need to copy the content of the `config.example` file in a new hidden file named `.config` + + cp config.example .config + +Now edit the `.config` file with your favorite editor. + +Here we can decide whether or not to upload the results of our tests to Fedora servers. +By default, running the tests will not automatically submit results. +They will just run and write results on a log file in /kernel-tests/logs/ + +* To submit results anonymously: edit the `.config` file with `submit=anonymous` + +* To submit results linked to your FAS username: edit the `.config` file with `submit=authenticated` and `username=` + +If you link your submission to your FAS username, you’ll also receive a https://badges.fedoraproject.org/badge/science-kernel-tester-i[Fedora badge!] + +The results of your test will be uploaded https://apps.fedoraproject.org/kerneltest/[here] + +=== Running tests + +IMPORTANT: *Before running the test, be sure your machine has no workload already, like other cpu intensive processes.You can check using the command: top* + +To run the basic set of tests, use this command: + + sudo ./runtests.sh + +To run the performance test suites, use this command: + + sudo ./runtests.sh -t performance + +The expected result is that the tests pass. +However, some tests may fail occasionally due to system load. +Anyway, add whatever results you got from the tests on the dedicated result page of the Kernel Test day! + +During a kernel test day, a dedicated web application page is created for uploading results, there you can fill a form with a description of the results you got. +Just Click on the *Enter Result* button and fill the form. +Enter a username in the *Username* field, in the *Profile* field enter a description of the machine you tested the kernel on, and choose the result of your test from the dropdown menu (failed or pass). +In the *Bugs* field you can write the number of a bug (or bug numbers divided by semicolons. i.e. '752855;25532') that you opened on Bugzilla, against that particular kernel. +If you found a bug in the kernel, please report it via https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=kernel[this link.] +If you don't have a Bugzilla account,you can still log in with your FAS account. + +NOTE: If a test fails repeatedly, consider helping by reporting the failure on https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=kernel[Bugzilla] + +Finally add any other comments or observations you want in the *Comment* field and Click the *Submit Query* button. + +_*Done!*_ + +Thanks for helping the fedora team in testing the newest kernel on your machine! + +If you want to help more: join the https://fedoraproject.org/wiki/QA[Fedora Quality Assurance] team and propose new test cases for the kernel that are not already on https://fedoraproject.org/wiki/KernelRegressionTests[this] page.