API/ABI stability undefined and unclear

[jadahl]

There is no documentation about API and ABI stability of libdecor. According to @GeorgesStavracas it's unstable and unsuitable for use outside of Flatpak, but the fact is that it's packaged in distributions, and used by applications packaged in traditional distributions. Distributions need some level of stability, e.g. compatible ABI version in the library name etc. If there is none, and libportal starts breaking ABI, things like nautilus can no longer use libportal, since it'll likely for the foreseeable future still be packaged in distributions.

[matthiasclasen]

When I started libportal, it was meant as a stopgap, for providing some library api for portals that aren't covered by toolkit apis (or aren't covered yet).

[smcv]

I thought we had reached agreement about this on #33, specifically in https://github.com/flatpak/libportal/issues/33#issuecomment-905779376, with the policy being similar to libgnome-desktop:

• the API is not long-term stable
• if the ABI breaks, we will bump the SONAME
• distributions can include libportal, but if they do, they must be prepared to do ABI transitions (which might involve patching apps for compatibility) when updating it to a new SONAME

[TingPing]

Unfortunately that wasn't documented anywhere and passed along to the new maintainer :/

AFAICT it has not broken ABI in ~2 years so its not exactly a difficult library to target. I would say an ABI break shouldn't be done often or lightly. But changing ABI if the need truly arises shouldn't be a huge problem.

[matthiasclasen]

Would be good to put the contents of that comment into writing somewhere in the repository