Files
komorebi/CONTRIBUTING.md
T
LGUG2Z 0725705298 ci(github): run the VM tests on KVM
`discover` asks the flake for the suites of each tier
(`legacyPackages.x86_64-linux.vmTiers`) and hands them to two matrices, so a new
directory under `nix/tests/vm/suites` is run without an edit to the workflow.
`vm-fast` runs the fast tier on every pull request, one machine per suite, as a
sandboxed `nix build` of the check. `vm-slow` runs on master, every week, and on
a pull request labeled `ci:vm-slow`; it builds the driver and runs it by hand,
outside the sandbox, so that the screenshots and journals of a failed run are
uploaded with `if: always()`.

A composite action installs nix with the store cached and, for the VM jobs,
frees disk space (a Plasma guest is a closure of about 10 GB), writes the udev
rule that makes /dev/kvm writable for the runner's user, checks it with `test
-w`, and adds `kvm` to nix's system features. KVM on hosted runners is
documented for public repositories only. Whether this private repository has it
is not known: the first run of these jobs says, and if it does not, they need a
different runner.

`lint` no longer runs `nix flake check`: on Linux that now boots every VM suite,
which a runner with no KVM cannot do. It builds the checks that need no virtual
machine, and `vm-lib`, the library's own tests.

CONTRIBUTING.md and docs/dev/vm-tests.md say what runs where.
2026-10-27 14:06:52 -07:00

4.0 KiB

Contributing to the Project

The project is a collection of contributions from both the project leaders and community members. There are many ways to contribute, this can include content in the project repositories, as well as contributing in public and private conversation, assisting users, writing blog posts, and many other ways.

How contributions are made

Contributions to the project primarily happen in the project source repositories, but may also occur in other places, such as discussion forums and public and private discourse.

Contributing content to the Project

In order for the project leaders to manage sustained progress toward the project goals and maintain project velocity, focus and quality, the project may adjust the license terms over time.

Content contributed to the project must therefore be provided under sufficiently liberal terms to allow these operations to proceed unimpeded. As such contributions are accepted with the following understanding:

  • Contributed content is licensed under the terms of the 0-BSD license
  • Contributors accept the terms of the project license at the time of contribution

By making a contribution, you accept both the current project license terms, and that all contributions that you have made are provided under the terms of the 0-BSD license.

Working on the code

nix develop (or direnv, through the .envrc) provides the Rust toolchain, a nightly rustfmt and the tools the checks use. rustfmt.toml uses an unstable option, which is why the formatter is a nightly one.

just check runs everything a change has to pass before it is pushed: the formatting check, clippy with warnings denied, the tests, and rustdoc with warnings denied. just fmt formats the Rust sources, and nix fmt every file type the repository has. nix flake check builds the same checks, plus cargo deny, as derivations; on Linux it also boots every VM test, which needs KVM.

VM tests

A change that needs a real KWin to be checked comes with a VM test, next to the Rust test that covers the same behavior against the fake desktop. docs/dev/vm-tests.md says how they are laid out, how to run one (just vm NAME) and how to add one.

Continuous integration

ci.yaml runs on every pull request and on every push to master, feature/* and hotfix/*, in this repository only. The lint job builds every check that needs no virtual machine and runs the repository's own lint rules, cargo-deny checks licenses and advisories, and the VM tests run on KVM in two jobs: vm-fast on every pull request and vm-slow on master, every week, and on pull requests labeled ci:vm-slow. A weekly workflow opens a pull request that moves flake.lock, and the same jobs run on it.

Commits

Commit messages follow the Conventional Commits specification: type(scope): description. The scope is the Rust module the change is in (wm, kwin, layouts), repo for repository files and markdown, nix for the flake and github for workflows. Every line of a message, the header included, is at most 80 columns, and the body says why the change is made.

Documentation lands in the commit that changes the behavior it describes, not in a later one.

Zero-Clause BSD

Permission to use, copy, modify, and/or distribute this software for  
any purpose with or without fee is hereby granted.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL  
WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES  
OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE  
FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY  
DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN  
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT  
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.