Contributing

Pull requests

Changes to this project should be proposed as pull requests on Github at:
https://github.com/lxc/incus-os

Proposed changes will then go through code review there and be merged in the main branch.

Code of Conduct

When contributing, you must adhere to the Code of Conduct, which is available at:
https://github.com/lxc/incus-os/blob/main/CODE_OF_CONDUCT.md

No Large Language Models (LLMs) or AI tools

All contributions to this project are expected to be done by human beings or through standard predictable tooling (e.g. scripts, formatters, …).

We expect all contributors to be able to reason about the code that they contribute and explain why they’re taking a particular approach.

LLMs and similar predictive tools have the annoying tendency of producing large amount of low quality code with subtle issues which end up taking the maintainers more time to debug than it would have taken to write the code by hand in the first place.

Any attempt at hiding the use of LLMs or similar tools in IncusOS contributions will result in a revert of the affected changes and a ban from the project.

Developer Certificate of Origin

To improve tracking of contributions to this project we use the DCO 1.1 and use a “sign-off” procedure for all changes going into the branch.

The sign-off is a simple line at the end of the explanation for the commit which certifies that you wrote it or otherwise have the right to pass it on as an open-source contribution.

Developer Certificate of Origin Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 660 York Street, Suite 102, San Francisco, CA 94110 USA

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.

An example of a valid sign-off line is:

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

Use your real name and a valid e-mail address. Sorry, no pseudonyms or anonymous contributions are allowed.

We also require each commit be individually signed-off by their author, even when part of a larger set. You may find git commit -s useful.

Building locally

You can build IncusOS locally. Only users specifically interested in the development and testing of new IncusOS features should need to do this.

We currently only support building IncusOS from a Debian 13 system though other Debian releases and Debian derivatives like Ubuntu may work as well.

After cloning the repository from GitHub, simply run:

make

By default the build will produce a raw image in the mkosi.output/ directory, suitable for writing to a USB stick. It is also possible to build an ISO image if you need to boot from a (virtual) CD-ROM device:

make build-iso

Testing

To test a locally built raw image in an Incus virtual machine, run:

make test

After IncusOS has completed its installation and is running in the virtual machine, to load applications run:

make test-applications

To test the update process, build a new image and update to it with:

make
make test-update

Debugging

When IncusOS is run in an Incus virtual machine, it is possible to exec into the running system to facilitate debugging of the system:

incus exec test-incus-os bash

You can also easily side-load a custom incus-osd binary into the virtual machine:

cd ./incus-osd/
go build ./cmd/incus-osd/
incus file push ./incus-osd test-incus-os/root/

Then exec into the virtual machine, stop the main incus-osd service and run the local copy:

incus exec test-incus-os bash
systemctl stop incus-osd
mount -o bind /root/incus-osd /usr/local/bin/incus-osd
systemctl start incus-osd

When debugging, it’s a good idea to install the debug application which contains a variety of useful tools, including a basic text editor (nano).

incus exec test-incus-os bash
curl --unix-socket /run/incus-os/unix.socket socket/1.0/applications -X POST -d '{"name": "debug"}'