libsoup 2 -> 3 migration plan and timeline (action required if you depend on libsoup)

[Michael Catanzaro]

Hi developers,

If you maintain a package that depends (directly or indirectly) on 
libsoup, this mail is important. ***Lots of applications depend 
indirectly on libsoup, even if you don't realize it!***

libsoup 3 (Fedora package: libsoup3) is incompatible with libsoup 2 
(Fedora package: libsoup). For better or for worse, the two cannot be 
linked into the same process, similar to GTK major versions. If libsoup 
2 and 3 get linked into the same process, they will crash at runtime. 
This means the transition from 2 -> 3 is going to be difficult and 
awkward, because libsoup is often used by libraries, and all libraries 
used by an application have to transition at the exact same time or 
else the application will crash at runtime. Whereas with GTK we have a 
few libraries that depend on GTK and need ported, with libsoup there 
are many more affected libraries. Accordingly, *this will not go as 
smoothly as we'd like.*

Still, hopefully we can manage this transition without applications 
winding up broken in stable Fedoras. The smoothest transition path is 
for upstream libraries to provide a different API version for libsoup2 
and libsoup3 versions, and ensure they can be parallel-installed. Some 
upstreams will do this while maintaining both versions at once, while 
others will depend on libsoup 3 for newer releases and use libsoup 2 
for older/stable releases. Either way is fine. Parallel-installability 
provides Fedora and other downstreams with maximum flexibility to 
manage the process. Libraries that use libsoup but do not provide 
parallel-installable API versions will be much harder to deal with, 
because apps that use libsoup 3 will be broken until the library 
switches to libsoup 3, and apps that use libsoup 2 will be broken after 
the library switches to libsoup 3. If the library has many 
dependencies, then it's hard to win in this situation.

Now because libsoup is a sensitive network-facing HTTP library written 
in an unsafe language and where CVEs may have disastrous impact, it is 
not safe to leave libsoup 2 hanging around indefinitely like GLib 1 and 
GTK 1. My proposal is to retire libsoup 2 in *Fedora 39* and for 
packagers to not attempt to bring it back after that happens. Proposed 
timeline:

 * September 2021 (done): libsoup 3.0 released
 * January 2022 (done): libsoup3 packaged for Fedora, included in F36
 * Today: the perfect time to port your packages away from libsoup2!
 * October 2022: Fedora 37 released with both libsoup 2 and libsoup 3
 * February 2023, right after F38 is branched: retire libsoup2 from 
rawhide, packages that depend on it break in rawhide
 * April 2023: Fedora 38 released with both libsoup 2 and libsoup 3
 * August 2023, ahead of F39 beta freeze: package carnage, retire all 
packages that still depend on libsoup 2
 * November 2023: Fedora 39 released without libsoup 2

Hopefully the 1.5 year timeline should leave adequate time for 
developers and maintainers to upgrade, while also acknowledging that we 
cannot wait forever and will not successfully port everything. Some 
packages will likely be retired at the end of this process, but 
hopefully we can keep that to a minimum. (GNOME upstream is trying to 
take care of GNOME core stuff, but we cannot possibly attempt to port 
all the extra apps or everything else that is in Fedora.)

Lastly, a special note on WebKitGTK. WebKitGTK especially benefits from 
libsoup 3 because libsoup 3 can do HTTP/2 and libsoup 2 cannot. There 
are three relevant APIs:

 * webkit2gtk-4.0: this is WebKitGTK for GTK 3 and libsoup 2
 * webkit2gtk-4.1: this is WebKitGTK for GTK 3 and libsoup 3
 * webkit2gtk-5.0 (subject to change): this is WebKitGTK for GTK 4 and 
libsoup 3

I intend to package -4.1 and -.5.0 soon and maintain them both 
indefinitely in the same source package. Neither are packaged yet, so 
you can't actually use them yet, but they'll be available soon. I 
intend to retire -4.0 at the same time libsoup2 is retired, if we stick 
to the proposed schedule above. (Only if libsoup 2 remains longer than 
I propose above would I be interested in removing -4.0 sooner.) The 
-5.0 package does not yet have stable API/ABI, but probably will in 
time for Fedora 37.

Michael