docs(design): Compass native shell GTK4/webkitgtk-6.0 migration record (RIG-1770) - #647
Open
rigel-mintaka wants to merge 2 commits into
Open
docs(design): Compass native shell GTK4/webkitgtk-6.0 migration record (RIG-1770)#647rigel-mintaka wants to merge 2 commits into
rigel-mintaka wants to merge 2 commits into
Conversation
…d (RIG-1770) Design record for the proactive flip of the Wails-v3 Linux desktop shell off the legacy GTK3 variant (gtk+-3.0 + webkit2gtk-4.1) onto Wails' default GTK4 + webkitgtk-6.0 stack, ahead of the gtk3 variant's removal in Wails v3.1. Matt's steer (2026-08-26): plan the migration now (option b) rather than absorb a forced migration coupled to v3.1's unknowns. Record only, no implementation. Grounds the four-surface flip (build tags, the gtk-closure.nix definition, packaging/CI, ledger) in file+line evidence: the app Go code is GTK-version-neutral, the bridge pump is framework-neutral, the pinned nixpkgs already ships gtk4 4.22.4 + webkitgtk_6_0 2.52.5 at the same WebKit release as webkitgtk_4_1, and the closure has one definition. Weighs three alternatives (stay-gtk3, dual-variant, CI-only canary) and carries a six-task plan with per-task Interfaces. Red-teamed by a design-critic pass before freeze (0 BROKEN); folded its findings: the sealed-CI-image hand-sync coupling (OQ5) promoted to load-bearing with a merge-blocking predecessor, the Wayland-vs-Xvfb gap stated as residual risk with a mandatory manual Wayland smoke, and the ci-matrix generator path corrected. Two load-bearing open questions (Wails pin target; SEA-1101 size-budget threshold) remain for Matt in the PR's Open Questions. Ledger-impact: none in this PR (design record only). At freeze the migration adds one new DL row (GTK4 default + closure swap, amending the SEA-1172 GTK closure definition in place); DL-110 stays Active. Encoded at impl, not here. Co-authored-by: Matt Wilkinson <matt@rigel.build>
rigel-mintaka
marked this pull request as ready for review
August 26, 2026 06:08
|
Compass engineering docs preview: https://compass-native-1770-gtk4-mig.compass-eng-docs.pages.dev Deployed from Changed pages: |
Address Matt's four points on PR #647: - Upstream maturity: GTK4 + webkitgtk-6.0 is the DEFAULT documented Linux stack in the current Wails v3 docs (reads GA, not opt-in experimental); reframe the "experimental upstream" tradeoff around the still-open wails#4957 tracking issue as the only residual immaturity signal. Flip proceeds regardless of the label. - CI backend: switch the e2e gate to Wayland (GTK4's default user backend) via headless weston + GDK_BACKEND=wayland as the primary lane, X11/Xvfb as a secondary regression lane. Closes the untested-default-path gap. OQ4 resolved; folded into T4. - Distro floor (24.04+/Debian 13+): ACCEPTED -- greenfield app, no legacy install base. Promoted from open tradeoff to a settled Global Constraint. - Renovate: do NOT auto-bump the Wails pin -- no automerge in-repo, it's a -beta prerelease, and T1's e2e gate must run on every pin move (F3). Keep manual until upstream ships stable. Recorded under the Wails floor constraint; OQ1 resolved. Compositor is an e2e-runner-only closure addition, so the tarball size budget (OQ2) is untouched. Ledger-impact: none (design record only; no DECISIONS.md row change) Co-authored-by: Matt Wilkinson <matt@rigel.build>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design record for the proactive flip of the Wails-v3 Linux desktop shell off
the legacy GTK3 variant (gtk+-3.0 + webkit2gtk-4.1) onto Wails' default GTK4 +
webkitgtk-6.0 stack, ahead of the gtk3 variant's removal in Wails v3.1. Matt's
steer (2026-08-26): plan the migration now (option b) rather than absorb a
forced migration coupled to v3.1's unknowns.
Record only, no implementation. Grounds the four-surface flip (build tags, the
gtk-closure.nix definition, packaging/CI, ledger) in file+line evidence: the
app Go code is GTK-version-neutral, the bridge pump is framework-neutral, the
pinned nixpkgs already ships gtk4 4.22.4 + webkitgtk_6_0 2.52.5 at the same
WebKit release as webkitgtk_4_1, and the closure has one definition. Weighs
three alternatives (stay-gtk3, dual-variant, CI-only canary) and carries a
six-task plan with per-task Interfaces.
Red-teamed by a design-critic pass before freeze (0 BROKEN); folded its
findings: the sealed-CI-image hand-sync coupling (OQ5) promoted to load-bearing
with a merge-blocking predecessor, the Wayland-vs-Xvfb gap stated as residual
risk with a mandatory manual Wayland smoke, and the ci-matrix generator path
corrected. Two load-bearing open questions (Wails pin target; SEA-1101
size-budget threshold) remain for Matt in the PR's Open Questions.
Ledger-impact: none in this PR (design record only). At freeze the migration
adds one new DL row (GTK4 default + closure swap, amending the SEA-1172 GTK
closure definition in place); DL-110 stays Active. Encoded at impl, not here.
Co-authored-by: Matt Wilkinson matt@rigel.build