Tom Gillespie <tgbugs@gmail.com> writes:

> Would it help if major releases maintained a mini-config that if added
> to init.el would allow users to retain old behavior? That way they
> wouldn't have to read the NEWS but could just add the relevant lines,
> or maybe even just call the org-old-default-behavior-9.1 or
> org-old-default-behavior-9.4. The workflow during development would be
> to account for any change to defaults in those functions. Thoughts?
> Tom

If people don't have time to read the NEWS file, I also doubt they would
be aware of the mini config file or have the time to add it to their
setup. There would be an additional burden on developers to maintain the
mini-config which might not actually result in any real benefit. I would
also be concerned this might setup an expectation which is difficult to
meet. It may not always be straight-forward to provide such a
mini-config and sometimes, it may actually be in the best interests of
the user to force a change on them because it brings other benefits that
outweigh the initial 'change pain'.

I do wonder if Org would benefit from adopting semantic versioning? This
could provide a way to convey more information to the user in the
version number e.g x.y.z => MAJOR.MINOR.PATCH where

- PATCH = bug fix only. No changes to API or interface
- MINOR = extensions (additions) to API or interface, but no change to
          existing API and interface
- MAJOR = breaking change - either API or interface has changed

In general, my experience has been that the org developers have worked
hard to keep things stable in a very complex environment. The challenge
is when there is a breaking change, how to effectively communicate this
and minimise surprises for the user and how to accurately gauge the
impact from a change.

At the same time, us users also need to take on some of the
responsibility and recognise that major version upgrades may break or
change their workflow. If you have a situation where stability of your
environment is critical to your work and your strapped for time so that
any change will be unacceptably disruptive, you need to adopt an upgrade
workflow which mitigates that risk. For example, my workflow allows me
to roll back any package which I upgrade. If I upgrade a package and it
breaks things and I don't have time to troubleshoot, I can roll it back.
Some distributions also include this feature. This is one area where I
feel the ELPA system could be improved. Right now, if you use the
org-plus-contrib package (or the org package) from either the org or
melpa package, it reports as something like org-plus-contrib-20201118,
which tells me very little apart from there is an update. I cannot tell
from this name if it is a major, minor or bug fix update. Not a big deal
for me as I can always roll back, but not everyone has that ability.

Change is inevitable and if we focus too much on not changing existing
behaviour or API, we run the risk of overly constraining development.
Communication of change is a challenge, but critically important. I feel
we would get the most benefit by focusing on how to communicate breaking
changes effectively and ensure when such change is introduced, as far as
possible, details on how to restore the previous behaviour are provided.


--
Tim Cross