Re: Policy proposal: Do not move existing functions/macros except in major version increments

[Adam Porter]

Hi Nicolas,

Nicolas Goaziou <address@hidden> writes:

> Hello,
>
> Adam Porter <address@hidden> writes:
>
>> The relatively recent moving of org-get-outline-path to org-refile.el
>> has caused breakage in Org itself in several places, e.g.
>
> [...]
>
>> Thankfully, Kyle has proposed a patch to revert that change.  I hope
>> it is merged.
>>
>> If it is not, when a new Org version is released with those changes
>
> What makes you think a new Org would be released in this situation,
> without fixing it first?

I don't know what will happen.  I don't know whether the Org maintainers
would consider the problem serious enough to avert (as you said later,
"it happens").  That's why I pointed out what the consequences would be
if the patch isn't merged, to encourage its merging.

>> I think changes like this should not be made without very careful
>> consideration of the wider implications.  These kinds of changes
>> create a not-insubstantial burden on maintainers of Org-related
>> packages to keep up with churn and maintain compatibility with
>> multiple Org versions (which are used in the wild for years--I know
>> of users still using Org 8, as well as Org 9 versions that are
>> included with older Emacs versions (e.g. Emacs 26.3 is still stuck in
>> Debian unstable, not migrating to testing, stable, or backports)).
>
> [...]
>
>> So, I propose that changes like these should not be made except in
>> major version increments, e.g. this change should have been delayed
>> until the release of Org 10.0.  It would be helpful for users and
>> package authors if they knew that changes like these would not be
>> made until the next major version increment.
>
> FWIW, I think this is too strong a requirement.
>
> This breakage is unfortunate, and I can hear the consequences it has
> on the Org ecosystem, but, hey, it happens. Note that moving part of
> Org elsewhere usually introduces less friction. This is a relatively
> exceptional situation.

Of course, I am biased here, but I feel like it's not quite as
exceptional as it ought to be.  The more Org-related packages I make and
maintain, the more version-specific workarounds I have to add due to
changed function names, signatures, etc.  These are sometimes necessary,
of course, but I think they should be made more carefully and
deliberately.

Of course, Org doesn't make any promises to third-party packages.  But
that is the issue, isn't it?  I'm saying that I think it should start
taking this issue a little more seriously.  :)

> Master is an unstable branch, relatively open to experimentation.
> Moreover, that experimentation happens before deciding if the next
> release should be 10.0 or 9.4, so it wouldn't help users or package
> authors.

That is a matter of policy, which is what I'm proposing.  When such a
change is desired (symbol name, function signature, etc), it should be
targeted at the next major version increment.  If the project as a whole
is not ready to make that increment, that change should be delayed until
then--it can be developed in a branch and merged when preparing the
major release.  These kinds of changes could even be documented in
advance, e.g. in a ROADMAP or PLANS file, or whatever you want to call
it, which would be more explicit and referenceable than merely a mailing
list post.

> It doesn't mean we cannot do better here. For example, I think we
> could improve the way Org loads its libraries. Ideally, external
> libraries should only (require 'org), and optionally, (require 'ox-*)
> or (require 'ol-*). Thus, changes like the one discussed here would be
> implementation details. For example, "ox-hugo.el" requires directly
> "ob-core.el", and now "org-refile.el", which is, IMO, a path to
> troubles. It should only require "org.el".
>
> The current situation is tricky though: "org.el" requires some
> libraries (e.g., "org-key.el", "org-table.el", ...), and some
> libraries require "org.el" (e.g., "org-capture.el", "org-element.el",
> ...). I expect "org.el" to be the entry point for the Org package, so
> loading should happen in one-way only.
>
> This would not solve everything, but it would certainly make things
> smoother for external libraries.
>
> WDYT?

That is a good idea, and one that needs addressing.  I'd be glad to give
some feedback on it, but in a separate thread, please, because it seems
like a different matter from the issue I'm raising and the proposal I'm
making.

Thanks,
Adam