Files
komorebi/CONTRIBUTING.md
T
LGUG2Z 9cb26daf38 build(nix): keybindings in the module
On NixOS the key bindings belong in the configuration, with the rest of
komorebi. services.komorebi.keybindings takes the format (skhd, whkd or sxhkd),
the bindings as text or as a file (exactly one of the two, asserted), the mode
(auto, engine or static; engine by default, as PlanMode::default() is),
chordTimeout (3000 ms), layout (us, the only one), strict and appAliases. skhd's
.load is refused by an assertion: the file it reads would not be in the store.

At build time the module runs komorebic hotkeys compile on the file in the
package komorebi-keybindings, whose share/kglobalaccel goes into the system
profile, where KWin finds the static shortcuts when the session starts. Its
diagnostics are in the build log and in diagnostics.txt, and strict passes
--strict, which fails the build on a warning or an error. execStart gains
--keybindings with the same store file, its format and mode, --chord-timeout and
an --app-alias per alias, so the daemon plans the file as the build did and runs
the bindings the build left to the engine. The unit already releases the keys
after the daemon stops.

The check keybindings-fixtures runs every file of the fixture corpus through
komorebic hotkeys compile --mode auto --dry-run, the command the module runs,
and diffs what it prints against nix/tests/keybindings.expected; it also checks
that docs/{skhdrc,whkdrc,sxhkdrc}.sample are the corpus's sample case.
nixos-module-eval gains the key binding scenarios: text, file, both, no format,
.load and a layout that is not us, and one with the typed config together with
key bindings, whose execStart has the checked file and then the keys. The corpus
gains the case vm, in the three formats: a binding a shortcut file can hold, and
one on the comma key, which X-KDE-Shortcuts cannot, so that the engine runs it
in auto mode. The VM suites vm-keys-skhd, vm-keys-whkd and vm-keys-sxhkd
configure the module with that case in their format and press both keys; they
share one script through the generator's script attribute.

For strict, nixos-module-eval has two scenarios with the same skhd text, which
has a line komorebic cannot read: strict = true and the default. Evaluation
never reads the key bindings, so the checks read the script of the build: with
strict it runs hotkeys compile --strict and exits 1 when that fails, without it
there is no --strict and the diagnostics are only printed to the build log. A
third check says the daemon gets the same command line either way. ARCHITECTURE
names them in the row for strict.

komorebic quickstart writes the sample skhdrc next to komorebi.json and
applications.json, from docs/skhdrc.sample, where the daemon and hotkeys compile
read it; the flake's source filter keeps that file for the build.

Docs: the user guide docs/usage/keybindings.md, the three sample files,
docs/example-configurations.md for KDE and NixOS, the options in
docs/installation.md, and the module's section of ARCHITECTURE. Whether the
engine or static shortcuts should be the default stays open in DESIGN: a static
shortcut took 233 ms to run its command at the median on KWin 6.8.1, the engine
3 ms, but only the static shortcut survives a dead daemon.
2026-10-28 07:39:49 -07:00

7.4 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, rustdoc with warnings denied, and the checks of the bridge. 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.

The bridge

bridge.js, the script komorebi loads into KWin, is JavaScript that KWin runs as it is: there is no package.json and no build step. Its types are JSDoc comments, which tsc checks against kwin-api.d.ts, the part of KWin's scripting API the bridge uses; something the bridge starts to use is declared there first. Its tests, bridge.test.js, run under node --test against a fake KWin. just check-js runs both, with the tsc and node of the dev shell.

The messages between the bridge and the daemon are in komorebi/src/kwin/fixtures, which the tests of both sides read. A change to a message changes the fixture, the bridge and the daemon in the same commit.

The NixOS module

nix/nixos-module.nix is services.komorebi, which the flake exports as nixosModules.default with its overlay. A change to it comes with a scenario in nix/tests/nixos-module.nix, the nixos-module-eval check: each scenario is a real NixOS system that is evaluated and never built, and its checks read the assertions, the unit and the options it evaluates to. It runs on a Mac too, with nix build .#checks.aarch64-darwin.nixos-module-eval. A change to what the unit does in a session also changes the VM suite module, which logs in to Plasma on a machine with the module and checks the daemon the unit runs. Every other VM suite runs on machines built with the module too.

Three files are generated from the Rust types and committed: schema.json and schema.asc.json (just jsonschema), and nix/komorebi-options.nix, which types the module's config (just nixgen, which needs schemars-nixgen, cargo install schemars-nixgen). A change to what komorebi.json or an applications.json can say regenerates them in the same commit, and the check schema-fresh fails when it does not. The first line of the options file is the hash of the schema it was made from, which is how the check tells without running schemars-nixgen.

A change to what komorebic hotkeys compile prints for a key binding file shows in keybindings-fixtures, which compares its output for every file of the fixture corpus with nix/tests/keybindings.expected: write the file again with the loop in nix/tests/keybindings.nix, and read the difference before committing it.

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.

The KWin effects

The patches in nix change the KWin effects komorebi drives. Each one is a derivative work of its effect, which is under the GNU General Public License version 3, and is under the same license. A patch starts with a header that describes the change and carries the license notice; patch skips the text before the first diff line. To change a patch, make the change in the effect's source at the version the package pins, and write the whole diff again with diff -ruN a b below the header. The check of each package, named after it (in nix/tests/effects.nix), builds the package and checks the files it installs, and for a patched package that the patch is in them:

nix build .#checks.x86_64-linux.kde-rounded-corners-komorebi-install
nix build .#checks.x86_64-linux.kwin-effect-geometry-change-komorebi-install

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. A change to a komorebic subcommand regenerates its page in docs/cli with just docgen.

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.