swayfx-mosaic/docs/UPSTREAM.md

Upstream maintenance

SwayFX Mosaic is an independent derivative of SwayFX, which is based on Sway. It is not endorsed by either project's maintainers. Preserve their license and attribution; see LICENSE and NOTICE.

Pinned source base

Item	Current value
SwayFX tag	0.6
Upstream commit	fd71a6bdc061bd633b488ae7b83e8a6981d22f86
Reported Sway base	1.12.0
wlroots series	0.20
SceneFX series	0.5

The historical locally installed Arch package was swayfx 0.6-1, but its exact source revision could not be reconstructed from available package metadata. The public SwayFX 0.6 tag is the verifiable project base; do not claim byte-for-byte equivalence with that older package.

Remote policy and history

origin is the canonical Forgejo project; github is the public mirror; upstream is SwayFX and is fetch only. No Mosaic branch or commit is pushed to SwayFX upstream. The project's main has clean public project history rooted in the imported SwayFX 0.6 base. The upstream remote remains an external source of new releases, not a project publication target.

Delta and versioning

The maintained production delta is patches/0001-mosaic-layout-viewport.patch on the pinned source commit. The package builds the full compositor because SwayFX has no stable external layout plugin ABI, then installs a distinct binary. Example versions are swayfx 0.6 and swayfx-mosaic 0.6+mosaic.1. A SwayFX 0.7 release does not automatically validate a Mosaic 0.7 package.

Forward-port procedure

1. Fetch upstream; inspect the release tag, commit, relevant source changes, and dependency versions.
2. Open a dedicated update branch and document changed architecture/UX/package assumptions before implementation.
3. Build the pristine upstream baseline at the candidate commit.
4. Rebase or manually forward-port the Mosaic patch. On conflict, inspect both implementations and adapt the delta deliberately; never force automatic patch application or accept rejected hunks.
5. Review exported patch scope; update pinned commit, package version, and checksums together.
6. Build Mosaic, run model and headless compositor tests, verify standard layouts, IPC, rendering, and package staging/file ownership.
7. Update known limitations, roadmap, and release notes with the observed result.

A failed patch check or changed compositor contract blocks that candidate release until resolved. It does not justify modifying the ordinary SwayFX package or using an ABI-incompatible binary workaround. The normal SwayFX package must remain independently updatable.