Re: Principled Handling of Breaking Changes

[Rudi C]

> what other breaking changes caused problems for you?

I remember these three:

- `tab-width`

- fontification in example blocks (https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=9daad41cc)

- `org-fold-core-style` changing to `text-properties` (from `overlays`) broke custom code I had for coloring links.

> Rather for Emacs in general. Would you be interested to post this

> suggestion on emacs-devel list?

That's also a good idea, but I don't remember being bitten by changes in emacs itself. It might help emacs adopt better defaults for new users though, as the backward compatibility of emacs makes its UX terrible for new users. 

> The very first section in https://orgmode.org/Changes.html lists

> breaking and important changes.

I don't care about "important changes" though, I just want the breaking changes ... I guess I should allocate the needed time for reading this anyway.

Thanks.

On Sat, Mar 16, 2024 at 1:48 PM Ihor Radchenko <yantar92@posteo.net> wrote:

Rudi C <rudiwillalwaysloveyou@gmail.com> writes:

> The recent upgrades to Org mode have been a source of great frustration for
> me. Many of the configurations I had previously set up stopped working as
> intended, and it took me several days to properly identify the issues,
> debug them, and find suitable workarounds.

Apart from the issue with tab-width you reported, what other breaking
changes caused problems for you?

> To address this concern, I suggest that all breaking changes in Org mode
> follow a versioning scheme similar to Perl's `use v5.34.0;`. This could be
> achieved by introducing an `org-defaults-use-version` variable, which would
> be set to nil by default, allowing the package to adapt its behavior as
> necessary. However, when `org-defaults-use-version` is set to a specific
> version, all configuration variables should adhere to the behavior
> associated with that particular version. Furthermore, I propose that all
> breaking changes be accompanied by a configuration flag, enabling users to
> disable the change if they so desire. By implementing these suggestions,
> users would be able to upgrade Org mode without the fear of spending hours
> dealing with frustration and debugging.

This might be a good idea, but not necessary for Org mode in particular.
Rather for Emacs in general. Would you be interested to post this
suggestion on emacs-devel list?

> PS: Is there a changelog that ONLY lists breaking changes? There should be
> one ...

The very first section in https://orgmode.org/Changes.html lists
breaking and important changes. Users are free to limit reading the
changelog to this first section. It is not clear for me why we need a
separate page.

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