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

[Ihor Radchenko <yantar92@posteo.net>]

> 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.

Sorry for not being clear.
I was referring to third-party packages Org optionally depends on.
Like geiser or citeproc or engrave-faces.

> 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.

Yes, but what if, say, the newest geiser version no longer supports the
Emacs version Org still supports?

> 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.

That's what we already do.
I mean, https://bzg.fr/en/the-software-maintainers-pledge/ :)

Public/private is the usual org-* vs. org--*.
We never break org-*. Even if we do, we first deprecate things.

> 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.

I hope that we never had unexpected changes. Isn't it for granted? I
felt like it was always the case in Org and Emacs forever.

It feels so obvious that I cannot even figure out how we could clarify
it in the manual.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>