12. 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.
12.1. 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 (see below).
- 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.
12.2. Code¶
- Basically follow the Linux kernel coding style
12.3. Documentation¶
- Use semantic linefeeds in .rst files.
12.4. 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.
12.4.1. 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.
12.4.2. CLI Tests - sharness¶
For high-level tests of the RAUC command line interface we use the sharness shell library.
You can run these checks manually by executing:
cd test
./rauc.t
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.
As many of these tests need root permissions, we recommend running them using the
qemu-test
helper below.
12.4.3. 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
).
To build and run an individual test, do:
make test/bundle.test
./test/bundle.test
To run all tests, run:
make check
This will also run the sharness 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!
12.4.4. 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.
To run the entire test suite, type:
./qemu-test
For optimal performance, run:
./qemu-test passthrough
which will pass through your host’s CPU features to the guest.
For interactive access to the test environment, use:
./qemu-test shell
12.5. 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:
- 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
- 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
- The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
- 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).