Development workflow

Use separate build directories and headless compositor tests. Ordinary development does not install into /usr, reload Sway, or change the active desktop session. The current package is experimental; see Packaging for the file-ownership contract.

Repository and remotes

Remote	Role	Push policy
`origin`	Canonical Forgejo project	Project changes
`github`	Public GitHub mirror	Same reviewed project commits
`upstream`	SwayFX source	Fetch only; never push Mosaic changes

main contains the project's public history: imported SwayFX 0.6 base plus Mosaic commits. The external upstream remote retains SwayFX history. Public instructions must not depend on a private local branch. Make focused development branches from main; merge or publish only after the source delta, tests, docs, and patch agree.

Base and prerequisites

The pinned base is SwayFX tag 0.6, commit fd71a6bdc061bd633b488ae7b83e8a6981d22f86, using wlroots 0.20 and SceneFX 0.5. Meson, Ninja, the base build dependencies, Python, and the headless test dependencies (kitty, grim) are needed for the respective checks. Review Upstream before changing the pin. The exact older local Arch package build source is not reconstructible; do not claim byte-identical provenance.

Pristine baseline build

Use a pristine checkout of the pinned upstream commit for baseline validation, or an already-retained baseline build known to come from that commit. Do not treat a Mosaic-modified tree as an upstream baseline.

meson setup build-baseline -Dwerror=false -Dsd-bus-provider=libsystemd
meson compile -C build-baseline -j 8
meson test -C build-baseline --print-errorlogs

The historical upstream baseline had no Meson tests. A fresh baseline build is especially important for an upstream update. The command above assumes the current working tree is the pristine baseline; use a separate checkout so the Mosaic tree is not altered.

Mosaic build and headless tests

From the project development tree:

meson setup build-mosaic \
  -Dwerror=false -Dsd-bus-provider=libsystemd \
  -Dmosaic-package=true -Dprefix=/usr -Dbindir=bin \
  -Dswaybar=false -Dswaynag=false \
  -Dman-pages=disabled -Ddefault-wallpaper=false
meson compile -C build-mosaic -j 8
meson test -C build-mosaic --print-errorlogs
python tests/headless-ipc.py
git diff --check

The headless script starts its own compositor socket; use its documented MOSAIC_BINARY environment variable for a nondefault build path. Do not send test commands to the running desktop's IPC socket. Record compiler/test failures, not only passes.

Staging and package checks

meson install -C build-mosaic --destdir /tmp/swayfx-mosaic-stage
find /tmp/swayfx-mosaic-stage -type f -print
makepkg --printsrcinfo
makepkg --verifysource

Inspect the staging manifest. With mosaic-package=true, the expected installed file is /usr/bin/swayfx-mosaic under the staging root. This is staging, not live installation. A full makepkg build is required before a release, with its own build/test output and manifest review.

Patch export

The development tree contains full SwayFX source for editing. patches/0001-mosaic-layout-viewport.patch is the production delta against the pinned base. After source changes, use tooling/export-patch.sh to regenerate it, then verify the patch against a clean checkout of the pinned upstream commit with git apply --check. Review the patch, refresh its package checksum, and validate the package build. git apply --check in an already-patched development tree is not a valid forward-application check.

Upstream update branch

Fetch upstream and identify the exact new release commit.
Create a dedicated branch/checkout for the new base; inspect SwayFX changes in affected files.
Update Architecture, UX, Packaging, Upstream, and limitations for any changed contract before implementing the forward port.
Adapt the Mosaic delta manually if the patch conflicts. Never force or silently skip hunks.
Build and test the pristine new base, then Mosaic and standard layouts on that base.
Run model/headless IPC/rendering tests, stage the package, inspect file ownership, and update the pin, version, patch, and checksums together.
Publish only after the new base is validated. The normal SwayFX package continues updating independently.

See Packaging and Upstream for release invariants. Desktop key bindings belong to user dotfiles and are not installed here.

4.5 KiB Raw Blame History