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

[Bastien]

Hi Adam,

Adam Porter <adam@alphapapa.net> writes:

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

IIRC this was the case for the change that triggered your first email,
it was in master, no?

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

I understand the burden.  We don't really follow the conventions of
semantic versioning.  We use "x.y.z" versions with z being for bugfix
releases and both y and x for... the rest.

Because we are slow at releasing so-called minor releases, they end up
containing some changes that users and developers should be aware of.
Hence the need to let them know about such changes.  I don't think
using a policy will help here, because definitions of "breaking" may
vary: is a change in a function's signature always a breaking change?
For every function?  Or just for core functions?  If so, which ones?
(See the many discussions in the npm universe about what to consider
a breaking change and worth a major release.)

In a word: even though stricter rules could somehow help, I do think
the main issue is about *communication*, not conventions.

> That's a very clever way to do it!  Thanks for your work on this.  

Thanks, I hope it will be useful.

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

The idea is that updates that are important enough to be listed on
updates.orgmode.org are the ones that *should* be somehow announced on
the mailing list.  If we let updates.orgmode.org monitor commits, then
people who are only reading the list will miss updates (which we
don't want, I think.)

That said, it would be nice to have a function that checks the data
from https://updates.orgmode.org/data/updates and warn the user when
there is a new upcoming change.

-- 
 Bastien