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

[Adam Porter <adam@alphapapa.net>]

Hi Bastien,

On 6/1/20, Bastien <bzg@gnu.org> wrote:
> Hi Adam,
>
> Adam Porter <adam@alphapapa.net> 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.
>>
>> https://lists.gnu.org/archive/html/emacs-orgmode/2020-04/msg00260.html
>> https://lists.gnu.org/archive/html/emacs-orgmode/2020-04/msg00259.html
>> https://lists.gnu.org/archive/html/emacs-orgmode/2020-04/msg00261.html
>
> ahem, my bad.  I made this bold (and wrong) move, and I broke code out
> of org-mode.
>
> I understand your proposal, and it's always good to be reminded that
> many people depend on Org's code out there.  It is not easy to spend
> time working on Org *and* tracking all these interesting extensions.

Of course, no one could be expected to keep track of all those things.
Such is the nature of writing software that runs in a Lisp image,
where anyone can use anything, and does.

> I agree with Nicolas that we should not put more constraints on the
> shoulders of Org current developers, especially because their time is
> limited - and obviously not enough to cope with every request.

I mostly agree with you.  My request is simply that, when a change has
the potential to break third-party packages, and it's a change, such
as this one, that mostly moves code around for organizational
purposes, that it be delayed until the next major version.  My goal
for such a policy would be to reduce the frequency of such changes
that third-party package authors have to write compatibility code for.
The (if (version< org-version ...)) workarounds become confusing for
authors and users, and somewhat of a maintenance burden.

> That said, we can make it easier for third-party developers to know
> what changes will be released in the future.
>
> See the "Upcoming changes" in https://updates.orgmode.org
>
> You can subscribe to this RSS feed:
> https://updates.orgmode.org/feed/changes
>
> Or check the data directly:
> https://updates.orgmode.org/data/changes
>
> To announce the change you see, I just used this email header:
>
>   X-Woof-Change: 9092c289 9.4
>
> That is the commit number where the change happens and the version
> in which the change will be released.
>
> The list of upcoming changes is emptied when a new major released is
> done, because the changes are then advertized in this file, as usual:
> https://orgmode.org/Changes.html
>
> I think that's a tiny distributed effort for developers and a easy
> way to track changes for third-party developers.

That's a very clever way to do it!  Thanks for your work on this.  If
it's feasible, you might also consider allowing committers to put such
a header in the git commit log and parsing it out of that, which could
make it even easier.

Thanks,
Adam