Transition to GtkSourceView 4

When porting an application to GtkSourceView 4/5 and GTK+ 4, the transition should be as smooth as possible. It means: being able to compile the code regularly and run the tests. Not doing all at once in one huge commit, but instead doing smaller and testable commits.

Edit: the namespace rename from GtkSource to Gsv has been cancelled. It will maybe be done in a later major version.

GtkSourceView 3.24 - done

Develop one more GtkSourceView 3 version, to have as few API breaks as possible for GtkSourceView 4 (other than removing deprecated APIs, and without counting the namespace change).

• New whitespace drawing API and deprecate the old one (683678) done

• Deprecate gtk_source_search_context_set_settings() (726981) done

• Improve the GtkSourceCompletionItem API (753649) done

Last stable version of GtkSourceView 3, being backward-compatible with previous 3.x versions. Apps should have zero warnings to continue.

This version has been released in March 2017.

GtkSourceView 4.0

It is planned to rename the namespace from GtkSource to Gsv (755752). But it is a quite big change for applications. So ideally app developers should be able to do one commit with only the namespace change, and be able to test that commit. If the app developer has to also port the code to GTK+ 4 at the same time, it would be a mess.

GtkSourceView 4.0 will still depend on GTK+ 3, but with the new namespace.

Rationales for doing a stable version of GtkSourceView (shipped by distros) with the new namespace and still depending on GTK+ 3:

• GtkSourceView based on GTK+ 4.0 (stable) will happen only in 2 or 3 years. Changing the GtkSourceView namespace will happen this development cycle. So it would be great if existing applications are able to use the new namespace while still using GTK+ 3. It would be one less thing to care about when porting an application to GTK+ 4.0. Also, between March 2017 and GTK+ 4.0, new apps or new libraries can be developed, depending on GtkSourceView. So when writing that new code, it would be better to use the new namespace.

• For us, backporting commits would be easier with the same namespace.

As is usual with library versioning, the major version is bumped each time there is an API break. So since the namespace change is an API break (and a big one), we bump the major version to 4. And when porting to GTK+ 3.90, we'll need to bump the major version one more time. The drawback is that the GtkSourceView and GTK+ versions will get out of sync. But already lots of GNOME libraries don't have the same versions as GTK+, so it is not a big problem.

The plan is:

• gtksourceview-4.pc, parallel-installable with GtkSourceView <= 3.24

• Still uses GTK+ 3

• GtkSourceView 3.99.1: remove all deprecated API done

• GtkSourceView 3.99.2: do a few other API breaks done

• GtkSourceView 4.0: rename the namespace from GtkSource to Gsv cancelled

The 3.99.x tarballs can be used by developers to port the code in finer-grained steps, to have smaller and testable commits. The 3.99.x tarballs will not be shipped by distros, developers need to compile them. But GtkSourceView 4.0 will be available as distro packages. The 3.99.x tarballs will be mentioned in the porting guide.

GtkSourceView 4.90

• gtksourceview-5.pc, parallel-installable with GtkSourceView <= 4.0

• Uses GTK+ 3.90 (which may force other API breaks in GtkSourceView)

Old proposals for handling the namespace change

Proposal 1 - GtkSourceView 3.50 intermediary version

• gtksourceview-3.50.pc, parallel-installable with GtkSourceView <= 3.24 and GtkSourceView >= 3.90

• Still uses GTK+ 3
• Remove all deprecated API and do a few other API breaks

• Rename the namespace from GtkSource to Gsv

• GtkSourceView 3.50 would be available as distro packages

Proposal 2 - a set of GtkSourceView 3.89.x tarballs

• gtksourceview-4.pc (the same as GtkSourceView 3.90)

• The first GtkSourceView 3.89.x versions still use GTK+ 3

• Would not be available as distro packages, app developers need to compile GtkSourceView

• GtkSourceView 3.89.1: remove all deprecated API

• GtkSourceView 3.89.2: do a few other API breaks

• GtkSourceView 3.89.3: rename the namespace from GtkSource to Gsv

• GtkSourceView >= 3.89.4: port to GTK+ 3.90

Tarballs would be available for each 3.89.x version. But distros would package only GtkSourceView 3.24 and GtkSourceView 3.90. In the porting guide for GtkSourceView 4, app developers would be encouraged to do the port incrementally by compiling and testing against each GtkSourceView 3.89.x version (3.89.1 -> 3.89.2 -> 3.89.3 -> 3.90/4.0).

For us, it would be more complicated to backport bug fixes from GtkSourceView 3.9x to GtkSourceView 3.24.

Proposal 3 - a set of 3.49.x tarballs and 3.50 intermediary version

Take the best of Proposal 1 and 2.

• gtksourceview-3.50.pc, parallel-installable with GtkSourceView <= 3.24 and GtkSourceView >= 3.90

• Still uses GTK+ 3

• GtkSourceView 3.49.1: remove all deprecated API

• GtkSourceView 3.49.2: do a few other API breaks

• GtkSourceView 3.50: rename the namespace from GtkSource to Gsv

• App developers need to compile the GtkSourceView 3.49.x versions

• GtkSourceView 3.50 would be available as distro packages