Goal

For v3.0.0 GA, GTK4 + WebKitGTK 6.0 becomes the default Linux build. GTK3 / WebKit 4 becomes opt-in for the remainder of the v3 cycle and is removed in v3.1.

Background

• GTK4 + WebKitGTK 6.0 support landed in v3 via feat(linux): GTK4 + WebKitGTK 6.0 support (opt-in via -tags gtk4) #4958 (merged 2026-02-06) and is currently opt-in via -tags gtk4.
• The v3.0.0-beta.1 draft release notes acknowledge this: "GTK4 / WebKitGTK 6.0 (Linux): behind `-tags gtk4`".
• For 1.0, we ship with the modern stack as the default of least resistance. GTK3 is end-of-distro-support on a growing list of mainstream distros.

Scope

• Invert the build-tag default in v3:
  • gtk4 no longer required — it's selected when no tag is given
  • gtk3 becomes the opt-in tag for the legacy stack (intended lifespan: v3 cycle only, removed in v3.1)
• Update Taskfile build steps under v3/internal/commands/build_assets/linux/ to reflect new defaults
• Update wails3 doctor to check for WebKitGTK 6.0 first, fall back to detecting WebKit 4 only if user opted into gtk3
• Update docs:
  • Migrate getting-started/Linux pages to drop the `-tags gtk4` instruction
  • Add a one-page guide for GTK3 opt-in + deprecation notice
• Update CI workflows (.github/workflows/) to build the GTK4 path by default; keep one matrix entry for the GTK3 path so we don't regress it before removal
• Update the beta.1 release notes to reflect the new default

Downstream notice

Packagers building Wails apps for Flatpak / AUR / nixpkgs / Debian have been opting into `-tags gtk4` manually. The flip will mean their builds switch silently unless they also pin `-tags gtk3`. Beta.1 release notes need a clearly-flagged migration paragraph for packagers.

Out of scope

• Removing GTK3 code paths from v3 (that's v3.1 work)
• Any new GTK4-specific features beyond what feat(linux): GTK4 + WebKitGTK 6.0 support (opt-in via -tags gtk4) #4958 already provides

Acceptance

• `go build` (no tags) on Linux produces a WebKitGTK-6.0 binary
• `go build -tags gtk3` still produces a working WebKit-4.1 binary
• `wails3 doctor` reports correctly for both paths
• Existing GTK4-tagged examples build with no changes