Contributing

Thank you for thinking about contributing to RAUC! Some different backgrounds and use-cases are essential for making RAUC work well for all users.

The following should help you with submitting your changes, but don’t let these guidelines keep you from opening a pull request. If in doubt, we’d prefer to see the code earlier as a work-in-progress PR and help you with the submission process.

Workflow

• Changes should be submitted via a GitHub pull request.

• Try to limit each commit to a single conceptual change.

• Add a signed-off-by line to your commits according to the Developer’s Certificate of Origin.

• Check that the tests still work before submitting the pull request. Also check the CI’s feedback on the pull request after submission.

• When adding new features, please also add the corresponding documentation and test code.

• If your change affects backward compatibility, describe the necessary changes in the commit message and update the examples where needed.

Code

• The projects coding style is inspired by the Linux kernel, but also deviates from it in some points. For details, see Code Style - uncrustify.

Documentation

• Use semantic linefeeds in .rst files.

Check Scripts & Test Suite

To ensure we do not break existing behavior and detect potential bugs, RAUC runs a test suite consisting of several components. Some of them only run in CI, but most of them can be executed locally. When working on a new feature or fixing a bug, please make sure these tests succeed.

Code Style - uncrustify

To maintain a consistent code style, we use the uncrustify code beautifier that also runs in the CI loop.

To make sure your changes match the expected code style, run:

./uncrustify.sh

from the RAUC source code’s root directory. It will adapt style where necessary.

CLI Tests - pytest

For high-level tests of the RAUC command line interface we use pytest.

You can run these checks manually by executing:

pytest test/

from the RAUC source code’s root directory but they will also be triggered by the general test suite run (see below). If you add or change subcommands or arguments of the CLI tool, make sure these tests succeed and extend them if possible. When touching the test code, make sure to run the ‘ruff’ linter/formatter on the changed code:

ruff format test/
ruff check test/

As many of these tests need root permissions, we recommend running them using the qemu-test helper below.

glib Unit Tests - gtest

For testing the different C modules of RAUC’s source code, we use the glib Test Framework.

All tests reside in the test/ folder and are named according to the module they test (test/bundle.c contains tests for src/bundle.c).

The tests are built by default. To explicitly switch them on or off in meson, use -Dtest= option:

meson setup -Dtests=true build

You can run each compiled test individually:

./build/test/bundle-test

To run all tests, run:

meson test -C build

This will also run the pytest CLI tests mentioned above.

Note

Although some of the tests need to run as root, do NOT use ‘sudo’, but use our qemu-test helper instead!

QEMU Test Runner - qemu-test

As many of the unit tests require root privileges and thus could potentially damage your host system, we provide a QEMU-based test environment where one can safely run all checks in a virtual environment.

Note that this does not run in a full VM with its own filesystem, but instead passes the host’s VFS to the guest using virtfs (and adds some overlays). This allows seamless access to the sources and binaries built on the host. Accordingly, the test dependencies need to be installed on the host.

To run the entire test suite, type:

./qemu-test

To run individual tests, you can either specify them by using the test= parameter:

./qemu-test test=install

The test name will be forwarded to meson test and thus must match the meson test names (e.g. install for a glib-based unit test or pytest-install for a pytest-based test).

Or you start an interactive shell with access to the test environment:

./qemu-test shell

From which you run the tests manually (as shown in the previous sections).

Additional parameters that you can add to a ./qemu-test call are:

passthrough:

for optimal performance (by passing through your host’s CPU features to the guest).

asan:

sets up environment variables to support the address sanitizer. This requires meson was set up with -Db_sanitize=address,undefined.

Interactive Test System

Beside providing a safe test environment, the ./qemu-test script also supports running RAUC interactively in the QEMU environment by calling:

./qemu-test system

This setup initializes QEMU to run with the RAUC service started, alongside a configured D-Bus and dummy target slots to simulate a real firmware update scenario. The configuration uses GRUB as a mock boot selection backend, allowing RAUC to interact with it as it would in a real system. Notably, rebooting the environment is not supported in this setup, meaning the testing is limited to a single boot cycle. This is sufficient for testing RAUC’s update mechanism but does not cover reboot-based validation.

Developer’s Certificate of Origin

RAUC uses the Developer’s Certificate of Origin 1.1 with the same process as used for the Linux kernel:

Developer’s Certificate of Origin 1.1

By making a contribution to this project, I certify that:

1. 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

2. 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

3. The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

4. 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.

Then you just add a line (using git commit -s) saying:

Signed-off-by: Random J Developer <random@developer.example.org>

using your real name (sorry, no pseudonyms or anonymous contributions).