Versioning and long term stability promise in GTK+

The plans set out in this post supersede those that were publicised after the Toronto GTK+ hackfest in June 2016.

This month, the GTK+ team will publish the first in a series of long-term stable releases. This will make GTK+ more predictable and reliable, while not inhibiting future GTK+ improvements.

These plans are a result of discussions held with a variety of stakeholders since initial plans were made at the GTK+ hackfest in Toronto last June.

Background

GTK+ has followed a fairly straightforward versioning scheme since the 2.0 release in 2002:

  • major versions designate the general API version
  • minor versions designate development cycles (if odd) and stable cycles (if even)
  • micro versions designate bug fix updates

Any API introduced in GTK+ is guaranteed to exist until the next major version; API introduced during a development cycle is guaranteed to remain once the stable cycle begins. Stable cycles do not provide new features or new API.

This scheme served us well, but its problems have become increasingly clear during the 3.x series, especially when coupled with 6 month, time-based development cycles. During the 2.x cycle new features in GNOME applications were forced to appear in additional libraries because the toolkit was too complex or moving too slowly. Since 3.0, the development pace of GTK+ has been picking up. GTK+ has been placed front and center, with new widgets and new functionality being introduced every six months. In order to implement these new widgets and functionality, though, some of the toolkit’s internals have been in a state of flux.

From a GNOME perspective, GTK+ has been a reasonably stable, albeit moving target, because GNOME developers and GTK+ developers can share feedback and proposals and quickly keep up with internal changes. From the perspective of the community, on the other hand, following GTK+ development has been more painful. Application developers outside of the GNOME project have had a hard time finding out about what changes in the toolkit will impact their codebases. The GTK+ team has attempted to improve its communication channels, but blogging about changes during development cycles hasn’t been enough for many in the wider community of GTK+ users.

Long-term stable GTK+ releases

GTK+ has three primary stakeholders: application developers who want feature and API stable releases; desktop developers who want access to development versions of GTK+ in order to introduce new functionality at a rapid pace (this includes most of the GNOME project); and the GTK+ team itself, which needs the ability to iterate on the internals of the library during longer development cycles.

The introduction of long-term stable GTK+ releases is designed to ensure that GTK+ strikes a good balance between each of these audiences. In particular, application developers will have access to a stable platform which nonetheless provides access to new GTK+ features that have been developed during the 3.x series, such as CSS styling, touchscreen support, HiDPI displays support, Wayland support, new widgets, the GTK+ inspector, and more.

GTK+ will continue to publish major, minor and micro releases. New major versions will be released once new features have stabilised, which is expected to be roughly every 2-3 years. When bumping to a new major version deprecated API will be removed. After that, this API series will be considered stable. New minor releases may introduce new widgets, or update the implementation of windowing system protocols in the GDK backends, but no additional features or theme changes will be allowed. Whereas previously minor releases were published every six months, now they will be produced as and when necessary. We’ll also keep doing micro releases for bug fixes and security issues, for at least three years. Maintenance after this point may continue, depending on the amount of volunteer resources available. Distributors of operating systems with long term support release cycles that extend past three years may want to contact the GTK team to establish a policy for backports.

Updates within long-term stable series will be ABI stable. Alongside these stable series, GTK+ development will continue in semi-stable development series. These development releases will contain some API changes between minor versions, although changes will be limited wherever possible. This is the path that we expect GNOME applications to take, but other application developers may choose this option if they want access to the latest features, at the cost of some potential porting work for each minor release.

While the GTK+ team reserves the right to change API during development series, this does not mean that the whole GTK+ API will constantly break each release; only specific, and hopefully rarely used parts of the API may change, and if the changes are too extensive they will very likely be delayed to the next major development cycle. We’ll ensure that these changes are well-communicated in advance.

The new versioning scheme

The new GTK+ versioning scheme is a modification of the “semantic versioning” scheme that we have followed until now. Once a new major stable release has been published, the development cycle starts and we will:

  • update the pkg-config file to a new major version, to allow GNOME developers to target the new API during development
  • keep the existing major version at the same number
  • update the minor version to 90 to indicate a development release

For instance, after the 3.22.0 release and at the start of the new development cycle, the pkg-config file will be called gtk+-4.0 and the version in the configure.ac file will be set to 3.90.

Every six months a new even development version will be released, such as x.90, x.92, x.94, until the GTK+ team is confident that the new API and feature set are stable. Each of these minor versions will bump the soname of the shared library, to ensure that automated tools can pick up the eventual changes and notify distributors and maintainers. Once we reach the point where the API and feature set is stable enough for the wider community to use, we will release a new major version (x + 1).0 and declare the API stable.

Once this point-zero release has been made, a new stable branch will be created, and the master branch will be bumped to the next point-ninety release and begin the new development cycle. The point-ninenty releases will be parallel installable with the previous stable releases.

gtk-versioning-scheme

3.22 will be the last minor release of the 3.x series, with the new versioning scheme coming into effect with 3.90. The 3.22 release is irregular in the scheme, in that it is a long-term stable version but won’t receive further minor releases and doesn’t have a .0 version number. This is a necessary transition step.

What’s next

More details about these plans, including specifics for library developers and distribution packagers, will follow in subsequent blog posts. The GTK+ development blog will also continue to provide updates about technical changes in GTK+ itself, in order to provide information about which changes will arrive in each upcoming major release.

We’re excited about these plans and are hopeful that they will usher in a new era for GTK+, in which application authors can be more confident in our platform, while still allowing the rapid pace of development that we have seen during the 3.x series.

The plans set out in this post supersede those that were publicised after the Toronto GTK+ hackfest in June 2016.

This Week in GTK+ – 15

In this last week, the master branch of GTK+ has seen 60 commits, with 10838 lines added and 6850 lines removed.

Planning and status
  • We’re close to the GTK+ 3.22 release, in time for GNOME 3.22.
  • Emmanuele has implemented a more comprehensive fallback path for mixed widget trees in his GSK branch.
  • Timm Bäder has taken the initial port of the build system to Meson done at GUADEC by Jussi Pakkanen and improved upon it.
  • The GTK+ road map is available on the wiki.
Notable changes
  • Carlos Garnacho merged his branch that implements graphic tablet support for the Wayland GDK backend; more details are available on his blog.
  • Jonas Ådahl ported GDK to the 6th version of the Wayland xdg_shell protocol, and he also fixed the behavior of transient-for windows created by sandbox portals on Wayland.

Bugs fixed

  • 770236 gtkbindings: Add an example for gtk_binding_entry_add_signal()
  • 770026 review comments for wip/wayland-tablet-v2
  • 770332 Notebook arrow icon wrong color after creating new tab
  • 769937 wayland: Port backend to use xdg-shell unstable v6
  • 764413 Wayland: not fullscreenable gtk+ apps can be fullscreened
  • 770374 Gtk Treeview Editable overshoots column width when column width is small
  • 770550 gtkplacessidebar: fix signal marshal
  • 770458 GtkAboutDialog issue with long credit lists and GtkScrolledWindow
  • 769788 Fix stacking order of flatpak portals on Wayland
Getting involved

Interested in working on GTK+? Look at the list of bugs for newcomers and join the IRC channel #gtk+ on irc.gnome.org.

This Week in GTK+ – 14

In these last two weeks, the master branch of GTK+ has seen 48 commits, with 4967 lines added and 3798 lines removed.

Planning and status
  • We skipped last week’s update due to most of the GTK+ developers being at GUADEC.
  • We had very productive discussions regarding the new release management and versioning scheme going forward; expect a full announcement on this blog.
  • GSK has been reviewed during GUADEC, and the work on the conversion of widgets to the new retained rendering API is ongoing; the API won’t be merged for 3.22, in order to improve rendering performance, shake out the last API issues found during porting, and especially avoid last minute breaking of applications using their own rendering on top of GTK+ windows, like Firefox and LibreOffice.
  • Carlos Garnacho has been porting the Wayland backend to the new tablet protocol; various changes have already landed in master, and the bulk of the review process is in bug 770026.
  • The work to support HiDPI displays in the Windows backend is progressing in bug 768081.
  • The GTK+ road map is available on the wiki.
Notable changes
  • Andreas Pokorny has been updating the Mir backend for GDK to improve the integration of GTK+ applications.
  • Timm Bäder added two new methods to GtkPopover, gtk_popover_popup() and gtk_popover_popdown(); these two new methods implement animated transitions, while calling gtk_widget_show() and gtk_widget_hide() will immediately show or hide the GtkPopover. With the addition of these two new methods, the GtkPopover:transitions-enabled property is now redundant and has been deprecated.

Bugs fixed

  • 769603 gtk+-3.20.8: underlink issue with ld.gold – build fails: ./.libs/libgdk-3.so: error: undefined reference to ‘shm_open’
  • 769601 Dead link in faq on gtk-question-index.html
  • 769568 Modification date display incorrectly wraps calendar days (and is inconsistent with GTK2 and Nautilus)
  • 768138 Update the GDK-Mir backend to fix a few problems
  • 769706 Add show/hide API to GtkPopover
  • 769402 regression in menu positioning on wayland
  • 768017 [Wayland] menus opened from access keys (mnemonic menu items) hide instantly
Getting involved

Interested in working on GTK+? Look at the list of bugs for newcomers and join the IRC channel #gtk+ on irc.gnome.org.

This Week in GTK+ – 13

In this last week, the master branch of GTK+ has seen 29 commits, with 4141 lines added and 3230 lines removed.

Planning and status
Notable changes
  • Ruslan Izhbulatov fixed two long standing issues with the keyboard layout and dead keys handling on Windows. GTK+ applications on Windows should now behave more in line with the rest of the platform, especially on US international keyboards. The changes have been applied to the master branch, but after further testing they should be backported to the 2.x stable branch.

Bugs fixed

  • 769287 GtkMenuToolButton:show-menu is emitted twice and breaks dynamic menus
  • 769485 Eliminate use of g_test_expect_message()
  • 712760 Clang static analysis fixes
  • 769451 Build failure of 3.21 (master) in Debian Unstable since 7-26-2016
Getting involved

Interested in working on GTK+? Look at the list of bugs for newcomers and join the IRC channel #gtk+ on irc.gnome.org.

This Week in GTK+ – 12

In this last week, the master branch of GTK+ has seen 28 commits, with 1868 lines added and 1422 lines removed.

Planning and status
Notable changes
  • Georges Basile Stavracas Neto has made the formerly private GtkShortcutLabel widget, used by the shortcuts window, part of the public API; the widget will be used in the GNOME Control Center keyboard options, and can be used by applications that allow editing their own keyboard shortcuts, like PiTiVi.

Bugs fixed

  • 768999 Floating point exception (division by zero) when running under Xvfb
  • 768930 reftests: override GSETTINGS_SCHEMA_DIR when running tests
  • 760944 resizing and geometry (snap to character cells) regressed with Gtk 3.19+
  • 755947 wayland: gnome-terminal does not fill entire area when tiled
  • 769047 GtkWidget <-> GtkStyleContext API not clear
  • 769205 Expose GtkShortcutLabel as a public widget
  • 769004 css test suite failures in 3.21.4
  • 768902 Font too small when using gtk_widget_override_font()
  • 769126 Can’t type astral plane characters into a GtkEntry using the Windows 10 touch keyboard
  • 769236 demos: Fix build failure
Getting involved

Interested in working on GTK+? Look at the list of bugs for newcomers and join the IRC channel #gtk+ on irc.gnome.org.

This Week in GTK+ – 11

In this last week, the master branch of GTK+ has seen 22 commits, with 6199 lines added and 1763 lines removed.

Planning and status
  • Matthias Clasen released GTK+ 3.21.4 and GLib 2.49.4, two new developers’ snapshots.
Notable changes
  • William Hua started merging the patches for relative positioning of menus and popups in the master branch.
  • Lapo Calamandrei did a small visual refresh of the styling of GtkCalendar in Adwaita.
  • Carlos Garnacho updated GDK to use the 2.0 version of the Wayland graphics tablet input protocol.
  • Matthias Clasen updated GTK+ to opt into the new structured logging API provided by GLib.

 

Bugs fixed

  • 769003 Adwaita: GtkCalendar uses a confusing style for week of year
  • 756579 GTK should let GDK position menus
Getting involved

Interested in working on GTK+? Look at the list of bugs for newcomers and join the IRC channel #gtk+ on irc.gnome.org.

This Week in GTK+ – 10

In this last week, the master branch of GTK+ has seen 16 commits, with 2500 lines added and 2092 lines removed.

Planning and status
  • Jonas Ådahl and William Hua are working on the feature branch that provides a new, declarative API for positioning popups and menus; you can read about it in the blog post that was published last Friday, as well as on bug 756579.
Notable changes
  • Matthias Clasen merged the patches, written by Philip Withnall, that implement a structured logging API in GLib. This work is still ongoing.
Bugs fixed
  • 768657 places-view: fix open action for locations without a mount or volume
  • 768659 gtk/gtkfilechoosernativeportal.c: Don’t use g_autoptr()
  • 768756 GtkFileChooserNativePortal uses incorrect response id
Getting involved

Interested in working on GTK+? Look at the list of bugs for newcomers and join the IRC channel #gtk+ on irc.gnome.org.

This Week in GTK+ – 9

In this last week, the master branch of GTK+ has seen 26 commits, with 2416 lines added and 180 lines removed.

Planning and status
  • Emmanuele Bassi is working on his GSK rendering branch, and Alex Larsson gave an initial review. Emmanuele also wrote a blog post on his GSK work.
  • The discussion on the release strategy is still going on on gtk-devel-list; opinions are still welcome.
  • William Hua has been rebasing his branch on the new, Wayland and Mir ready popup positioning API, which replaces positioning via global coordinates.
Notable changes
  • Matthias Clasen landed the “portals” implementation for negotiating access to resources outside of a sandbox in both GLib and GTK+. You can read more about it on his blog.
Bugs fixed
  • 768485 Change the priority of the window-close idle to G_PRIORITY_DEFAULT
  • 768499 portal support for gtk+
  • 768546 Wrong documentation for the “move-viewport” signal of GtkTextView
Get Involved

Interested in working on GTK+? Look at the list of bugs for newcomers and join the IRC channel #gtk+ on irc.gnome.org.

This Week in GTK+ – 8

In this last week, the master branch of GTK+ has seen 23 commits, with 1154 lines added and 121 lines removed.

Planning and Status
  • Matthias continued to work on the portal branches of GLib and GTK+.
  • Emmanuele continued to make gsk render widgets on the gsk-renderer branch.
  • Philip Withnall is working on a patch series to make GLib support structured logging to the systemd journal here.
Notable Changes
  • Carlos Garnacho improved compatibility of Wayland clipboard handling with legacy X clients.
  • Matthias made it possible to hide the preview button in print dialogs.
  • Eric Koegel added support for the Xfce session manager to GtkApplication
  • Georges Basile Stavracas Neto added support for background-blend-mode to the GTK+ CSS machinery.
  • Over in GLib, Matthias added a new gio utility that combines the functionality of the various gvfs commandline tools into one.
Bugs fixed
  • Bug 767965Improve heuristics to detect remote filesystems
  • Bug 768184headerbar: don’t throw a warning if title widget is hidden
  • Bug 768082 – Copying from Wayland to NEdit doesn’t work
  • Bug 768177 CLIPBOARD target request after PRIMARY request times out
  • Bug 768142 Incorrect order of $(LIBS) and $(OBJS) in Makefile.example caused “undefined reference”
  • Bug 693203GtkApplication does not support Xfce session manager
  • Bug 768305Gtk+ should support background-blend-mode
Get Involved

Interested in working on GTK+? Look at the list of bugs for newcomers and join the IRC channel #gtk+ on irc.gnome.org.

This Week in GTK+ – 7

In this last week, the master branch of GTK+ has seen 29 commits, with 4744 lines added and 4340 lines removed.

Planning and Status
  • GTK+ 3.21.3 was released
  • Matthias continued to work on the portal branches of GLib and GTK+.
  • William Hua is reworking the menu positioning API from bug 756579 following the hackfest discussion.
  • Emmanuele pushed a new revision of the gsk branch.
  • Carlos Soriano is working on a new pathbar implementation for the file chooser and nautilus.
Notable changes
  • Emmanuele fixed some fallout in firefox from the GdkDrawingContext introduction.
  • Ray Strode cleaned up some headerbar code and added support for expanding children
  • Matthias fixed a crash in GtkColorChooser and another one in GtkInspector
Bugs fixed
  • Bug 767851 – popover arrows broken in some orientations
  • Bug 767849 – crash in focus handling
  • Bug 724332 – GtkHeaderBar need to support an expand property
  • Bug 768025 – entry.warning & entry.error broken
Get Involved

Interested in working on GTK+? Look at the list of bugs for newcomers and join the IRC channel #gtk+ on irc.gnome.org.