Principled Handling of Breaking Changes

Principled Handling of Breaking Changes

[Rudi C]

[-- Attachment #1: Type: text/plain, Size: 1298 bytes --]

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. I believe that Org mode would
benefit greatly from adopting a more principled approach to backward
compatibility.

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.

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

PPS: Please use Reply to All when responding to this message.

[-- Attachment #2: Type: text/html, Size: 1353 bytes --]

Re: Principled Handling of Breaking Changes

[Ihor Radchenko]

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>

Re: Principled Handling of Breaking Changes

[Rudi C]

[-- Attachment #1: Type: text/plain, Size: 3082 bytes --]

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

[-- Attachment #2: Type: text/html, Size: 4250 bytes --]

Re: Principled Handling of Breaking Changes

[Ihor Radchenko]

Rudi C <rudiwillalwaysloveyou@gmail.com> writes:

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

I think I need to clarify a bit about how we consider changes in Org mode.

- We rarely touch default values in user customization - same as what
  Emacs does. Every time we do go ahead with changing customization
  defaults, we consider such a change very carefully.

  Changing tab-width has a strong justification - we are aiming to
  stabilize Org mode markup and register it officially. So, all aspects
  of Org markup will eventually be decoupled from Emacs customization.
  (the other question is whether we can avoid co-lateral damage; let's
  discuss it in the other thread)

- We reserve the right to change internal implementation details of Org
  mode at will. Like the details how folding is implemented. Any other
  policy would make it impossible to add new and improve existing
  features of Org mode. Emacs has the same policy.

  Yet, we take care to communicate major changes in the internals to
  users who might be relying upon implementation details.

- We also reserve the right to alter undocumented features of Org mode.
  We do not exercise this right at will though - if we can keep some
  undocumented feature without too much effort, we do.

  Example block fontification was one of the undocumented features. As
  per the commit you linked to, we restored example block fontification
  and added a comment in the code to avoid future accidental breakage
  upon reporting.

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

The exact name of the section is "Important announcements and breaking
changes". By "important announcements", we really mean important -
something that may need action. For example, changes in folding
machinery where not breaking (they did not break any documented
feature), but certainly important enough to bring to everyone's
attention.

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