swayfx-mosaic/CONTRIBUTING.md

Contributing

SwayFX Mosaic is experimental compositor work. Changes should stay narrowly focused on the Mosaic / Spatial Canvas layout and its packaging/tests.

Before changing code

Read:

• README.md
• docs/ARCHITECTURE.md
• docs/DEVELOPMENT.md
• docs/UPSTREAM.md

Scope

Appropriate contributions include:

• Mosaic layout model;
• geometry, viewport and scene behavior;
• focus/input behavior required by Mosaic;
• IPC additions required to expose Mosaic state;
• Mosaic tests;
• patch maintenance and packaging.

Desktop shell features, themes, personal key bindings and unrelated SwayFX customizations belong elsewhere.

Required checks

At minimum:

meson compile -C build-mosaic -j 8
meson test -C build-mosaic --print-errorlogs
python tests/headless-ipc.py
git diff --check

For upstream rebases, also rebuild the pristine baseline and validate the standard Sway layouts.

Compatibility

Do not introduce a package conflict with ordinary swayfx.

Do not install over /usr/bin/sway.

Do not treat QuickShell or an external daemon as the authoritative Mosaic state store.

Commits

Keep commits reviewable and explain:

• the compositor invariant being changed;
• why the change belongs in Mosaic;
• the validation performed;
• any known limitation.

Never hide failed tests or force-apply the Mosaic patch to an unvalidated upstream revision.