Re: Concrete suggestions to improve Org mode third-party integration :: an afterthought following Karl Voit's Orgdown proposal

[Tim Cross]

Ihor Radchenko <yantar92@gmail.com> writes:

> Tim Cross <theophilusx@gmail.com> writes:
>
>> ... while I totally agree we should work
>> very hard not to break compatibility or adversely affect other projects
>> which are built on top of org mode, like org-roam, we also don't want to
>> find ourselves in a position where we cannot improve/enhance org mode
>> because of the impact it has on other projects.
>
> Well. We have no direct control on the other projects. However, not
> doing anything about the fact that other project keep appearing is
> nothing but a call for more compatibility issues. If we do not clearly
> specify relatively stable syntax or API, the other projects will
> inevitably use internal implementation details and could be broken more
> easily. For example, my recent patch to org-element broke org-roam
> because org-roam relied on some undocumented behaviour of
> org-element-at-point.
>
>> Having thought about this whole thread and other recent posts, I still
>> feel any concern or reference to third party libraries etc is misguided
>> or at the least, irrelevant. Most of the suggestions are fine and would
>> be beneficial to org mode (such as clearly defined, consistent and
>> documented syntax). The fact 3rd party libraries would also benefit from
>> this is a bonus, but largely irrelevant.
>
> You read "Org mode third-party integration" as benefit for third-party
> libraries. I read it as benefit for Org from third-party libraries (as
> opposed to no benefit and potential complains from third-party library
> users).
>

I think 3rd party libraries are a benefit to org users. On the whole,
they are of no direct benefit to org-mode (if they are, then they are a
good candidate for inclusion into org mode). The relationship is very
similar to what Emacs has with all the external packages which are not
part of Emacs. There is no direct benefit to Emacs from all these
packages, but there is huge benefit for the Emacs community. Emacs
changes and evolves as necessary to keep it relevant, maintainable and
up-to-date with user expectations. At times, it will make changes that
are breaking on 3rd party libraries or require 3rd party libraries to
update/modify how they interact with Emacs. These changes are not done
lightly and are done so as to minimise impact to these 3rd parties.
However, Emacs does not concern itself with 3rd party libraries - it
focuses on making Emacs better and leaves 3rd party libraries to
themselves.

Placing too much focus on 3rd party libraries runs the risk of the tail
wagging the dog. Org mode should focus on what org-mode needs to do to
be performant, maintainable and minimise bugs. Having clear syntax
specifications, good unit tests, a clear and consistent API and
documentation all contribute to org-mode stability and maintainability.
Coincidentally, these are also the things which will most benefit 3rd
party libraries. However, should there be some justified reason to
change the syntax or the API in order to improve performance,
or maintainability, we should not feel constrained from doing so because
it will impact on 3rd party libraries. Instead, we should make such
changes in a staged manner and provide a reasonable time for 3rd parties
to be updated to work with the changes and only introduce breaking
change in new major versions.