Re: [MAINTENANCE] Do we have any backwards-compatibility policy for third-party packages?

[Tim Cross]

Ihor Radchenko <yantar92@posteo.net> writes:

> Hi,
>
> Org promises to support the last three Emacs releases.
> However, it is less clear what is our policy wrt third-party packages.
>
> We do need third-party packages, for example, in babel backends.
> Sometimes, we have to make changes to the ob-*.el files in order to
> accommodate changes in the required third-party packages. Like in recent
> changes to ob-scheme where `run-geiser' function is now obsolete
> upstream.
>
> Should we try to support obsolete functions/variables in third-party
> packages? Should we try to work around breaking changes and support both
> before/after package versions?
>
> The answer is not obvious as older Emacs versions might not be supported
> by some third-party packages. Then, logically, we have to support older
> package versions compatible with the oldest Emacs version we support.
> But it might be hard to keep track of such scenarios.
>

It might be worthwhile defining what is meant by 3rd party packages.

For example, ob-scheme relying on geiser as a 3rd party package is one
thing. Org roam is another type of 3rd party package. I think they need
different approaches. The first is about our (org) interface to them and
the latter is about their (org roam) interface with org.

For the former (e.g. geiser type), I don't think backwards compatibility
is as important. Thanks to package.el and GNU ELPA/NONGNU ELPA, it is
fairly trivial to update to the current version. We just need to support
the current version.

For the latter (e.g. org-roam), backwards compatibility is much more
important. Org needs to provide as stable a public API for such packages
as possible. It may even be worthwhile separating the API into a
public/external API and an internal/private API. The former would be as
stable as possible and when changes are made, all efforts to provide
backwards compatibility are made. The latter is also stable, but more
subject to change. It is the API intended for internal org use. If
external packages use it, it is at their own risk. We would still try to
keep it stable, but with less of a guarantee and we may not provide
backwards compatibility if doing so was going to cause too much
complexity or maintenance burden etc.

The big thing here is IMO avoiding surprise. We probably should add a
section to the 'Hacking' section of the manual which outlines our
position wrt backwards compatibility and API (public/private) and change
etc. I think most people expect change (even if they might not like
it). What they don't like is unexpected change. As long as we are
conservative and communicate change when necessary, we will likely be
OK.