This page was part of the discussion of the development of GTK+ 4.x and which led to the GTK+ versioning and long term stability promise; it is preserved for historical reasons.

Why do this?

We are trying to offer people an explicit tradeoff between two good options. Previously it was unclear to application authors what they were signing up for, and both options open to them were not so good.

The current situation puts application developers between a rock and a hard place, and we've received a lot of feedback to that effect. Either you can target your application to GTK 2.24, which is rock-solid but six years old (and was already getting rusty when it became stable — it's more like a UI toolkit for the year 2000.) Or you can target your application to GTK 3, which is a more modern UI toolkit, but which has seen breakages on minor releases that people have found very unpleasant. For example, the CSS machinery changed in several consecutive minor releases and broke people's CSS themes.

The problem this scheme tries to solve is to allow people to target their apps to a stable version without it being ancient, and thereby serve application developers' needs better than we have done in the 3.x series.

We also hope that more frequent stable release series will make it more attractive to use GTK outside of GNOME than it has previously been.

As an application developer, should I use the stable or unstable series?

If you want stability, and don't want to have to update your app when GTK makes a minor release, then you pick the stable series.

If you want the newest features, you can opt in to the unstable series, which will be more work. However, we expect that most GNOME applications will track the unstable series because they will have enough of a need for new features and enough active developers to handle the extra work.

How does the stable series affect me as an application developer?

What you gain is that your UI toolkit will be at most 18 months out of date instead of 10 years. You also get the guarantee that you can port your app to the a stable version without fear that your work will be undone by breakages in upcoming releases.

The flip side of having a stable release that's not too long out of date, is that it won't stay supported as long as GTK 2 has. However, if you release your app as a Flatpak, you can leave it on a stable release forever if you want to.

How does the unstable series affect me as an application developer?

You gain the newest features, delivered more rapidly. You also get the guarantee that within 2 years, the unstable release will become stable, so you can plan when to step off the porting train.

The drawback is that you will need to fix your app on a GTK minor release from time to time while the series is still unstable. This is just as in the 3.x series, but depending on the release you will probably have to fix more than just CSS selectors.

Why can't every GTK release be compatible, in the sense of not breaking my apps and themes?

That was our goal for 3.x, as it was in 2.x, but the work required to modernize the toolkit during the 3.x series required some breakage in practice. GTK 2.x was an old-fashioned UI toolkit, and in order to keep GTK relevant we have to keep a fast pace of developing new features.

There's a tradeoff: the more stuff you break, the more features you can implement. Conversely, the stricter your compatibility requirements are, the more expensive it is to implement new features.

In addition, there is a gray area around compatibility requirements. For example, is it an ABI break if a label shifts one pixel inside a button when running against a later release? The answer is up to the individual project's maintainers, but it is not clear-cut.

No, seriously, $OTHER_PROJECT manages it. Why can't you?

We believe that given the above tradeoff, this is the best use of our resources balanced against our application developers' needs for a modern UI toolkit with fast-paced feature development. Other projects have other needs: a smaller API surface, or less need for innovation, for example.

Why can't every minor GTK release be API/ABI compatible with the previous one?

With the existing policy, we've been reluctant to expose lower-level functionality to app developers, preferring to expose as small as possible an API surface and keeping many things in private headers. With the freedom to break API, we can expose these formerly-private APIs to developers in an unstable release, with appropriate caveats. Then, when the unstable series becomes stable, these now-stable APIs can remain public.

One example reason for breakage is to have the toolkit conform to modern expectations of, for example, input devices and display servers. The more we try to keep API and ABI compatibility intact while still implementing large features like Wayland or touch support, the more expensive the implementation will be. Read Christian Hergert's mailing list post for some of the ambitious changes that GTK needs to make in 4.0 and beyond.

Why is it a goal to break API?

It's not a goal. If there are no features that require breaking API in a release, then we won't go around looking for something to break.

Why bump the soname every six months?

Standard practice for distributions is to bump the soname when there is an ABI break. Given that ABI breaks can be even minor things, and we are planning to allow both API and ABI breaks in unstable releases, we assume that each unstable release will require a soname bump. Of course, if there happens to be nothing in a release that requires a soname bump, then we will not bump the soname.

This will be difficult for source-based distributions and we'd welcome ideas on making it easier.

I need to target GTK 2 because GTK 3 doesn't have good cross-platform support. Won't this make my life harder?

This is certainly a problem and we'd welcome input from people who are affected by it. It took a long time since the 3.0 release to bring a usable version of GTK 3 to Windows platforms, and we need to have a good developer story for this.

Aren't you just going to leave the stable series to rot, in practice?

No. As Emmanuele Bassi points out, that has not happened to the GTK 2.x stable series:

• Since [the 2.24.0 release in January 2011], the 2.24 branch — i.e. the “feature frozen” branch has seen 873 commits (as of this afternoon, London time), and 30 additional releases. Turns out that people are being paid to maintain feature-frozen branches because that’s where the “boring” bits are — security issues, stability bugs, etc.

Why did you decide this without consulting the community?

This reason for this proposal in the first place is because of feedback from community members unhappy with GTK's current practices.

It's not our intention to restrict the discussion to the people who were able to be present in the hackfest room in Toronto. Nothing has been decided yet, this is a proposal on which we are soliciting the opinions of GTK and application developers. Come discuss it on gtk-devel-list@gnome.org and #gtk+.

More points for discussion / FAQs that need answering

• Why can't the stable release cadence be longer than 2 years?
• Why can't the stable releases stay supported for longer than 2 years?
• Why release API-breaking major versions on a cadence? Can't you just do it only when necessary?

• How about a GtkPrivate library and #define I_WANT_UNSTABLE_API?

• How can I support both the stable and unstable releases?
• How will this affect theme developers, since they don't get to choose what version to target like app developers do?