How to test kernels in -proposed
=================================

Ubuntu kernels are uploaded to the -proposed pocket for testing before being
published to -updates and -security. You can install these prerelease kernels to
use and test them sooner, but you must opt in to package from -proposed as they
are not enabled by default.

This document is based on `EnableProposed`_ from the Ubuntu Wiki.

Adding the -proposed pocket to software sources
-----------------------------------------------

To install packages from -proposed, you can enable it via the GUI or CLI.

GUI
~~~

1. Open "Software & Updates".
2. Navigate to the "Developer Options" tab.
3. Enable the option that says "Pre-released updates (<series>-proposed)".

CLI
~~~

.. tabs::

   .. tab:: Noble 24.04 (and newer)

      Add \"<series>-proposed\" to the ``Suites:`` line in the
      :file:`/etc/apt/sources.list.d/ubuntu.sources` file.

      .. code-block:: text
         :emphasize-lines: 3

         Types: deb
         URIs: http://archive.ubuntu.com/ubuntu
         Suites: noble noble-updates noble-backports noble-proposed
         Components: main universe restricted multiverse
         Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg

   .. tab:: Mantic 23.10 (and older)

      If not, add this line for your Ubuntu release in
      :file:`/etc/apt/sources.list` or another file in
      :file:`/etc/apt/sources.list.d/` (for x86):

      .. code:: text

         deb http://archive.ubuntu.com/ubuntu/ <series>-proposed restricted main multiverse universe

      Or, if you're architecture is not x86:

      .. code:: text

         deb http://ports.ubuntu.com/ubuntu-ports <series>-proposed restricted main multiverse universe

Install the pre-release kernel
------------------------------

First, update the sources cache if you haven't already:

.. code:: console

   $ sudo apt update

Now you can install the kernel as normal. If the kernel in -proposed has the
highest version of any pocket, you can install it with:

.. code:: console

   $ sudo apt install linux-<flavour>

If you want a specific (earlier) version, you may have to specify the version:

.. code:: console

   $ sudo apt install linux-<flavour>=<version>

After installing, reboot your machine or VM. After booting up again, verify the
correct kernel is loaded with:

.. code:: console

   $ uname -r

This should print the correct version and flavour.

Testing the kernel
------------------

With the new kernel installed, you can begin testing.

If you do not have your own test suite and would like an example workload, the
built-in Linux selftests are a good starting point. To run these, you need to
compile the tests in the kernel source.

.. code:: console

   $ sudo apt source linux-image-unsigned-$(uname -r)

Now you can build and run the selftests from the extracted source:

.. code:: console

   $ cd <source dir>
   $ sudo make -C tools/testing/selftets run_tests

Of course, this is one of many ways you can test a running kernel. Here are
some other examples of pre-existing testing projects:

* `Linux Test Project`_
* `stress-ng`_

What to do if a regression is found
-----------------------------------

File a bug report in Launchpad
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On your system with the kernel installed, you can use the "ubuntu-bug" tool in
the terminal:

.. code:: console

   $ ubuntu-bug

Or you can file a bug manually online: https://bugs.launchpad.net/ubuntu/+filebug.

Make sure to target your kernel source package and Ubuntu series.

More information about bug reporting can be found on Ubuntu's `ReportingBugs`_
documentation.

.. LINKS

.. _EnableProposed: https://wiki.ubuntu.com/Testing/EnableProposed
.. _Linux Test Project: https://linux-test-project.readthedocs.io/en/latest/
.. _stress-ng: https://github.com/ColinIanKing/stress-ng
.. _ReportingBugs: https://help.ubuntu.com/community/ReportingBugs