Re: [PATCH] Rename headline to heading

[Tim Cross]

Jim Porter <jporterbugs@gmail.com> writes:

> On 8/14/2021 3:54 PM, Tim Cross wrote:
>> I'm not convinced a transition period will help in this case. At some
>> point, users will need to update their capture templates regardless.
>> Provided this impact is clearly outlined in the NEWS.org file (I think
>> there should be a specific reference to capture templates added in the
>> patch to NEWS.org) and provided this change is applied to the next
>> release only, no transition period is necessary.
>
> I think having a transition period would be helpful here. First, this helps to
> account for users who may run multiple versions of Emacs with the same config.
> This could happen for a few reasons, such as running on different revisions 
> of a
> GNU/Linux distribution, or even just because the user is testing out the
> latest/next version of Emacs.
>
> In addition, a transition period makes it easy to inform users about what they
> need to do to upgrade. Without any compatibility code, the error message
> (likely) won't be very helpful, whereas even some minimal compatibility code
> could tell the user what edits to make to their config. While everyone 
> *should*
> read the manual/NEWS, it's easy to miss things sometimes, and errors like this
> can be non-obvious, especially if the compatibility issue isn't directly in 
> the
> user's config, but in some other third-party package.
>
> As such, I think it would be nice to have a transition period of at least one
> Emacs version. Beyond that, I don't see any problems with excising old
> compatibility code. As you say, users will have to upgrade at *some* point.
>

While I understand the intent here, I think it is a false sense of
helpfulness.

At some point, your transition period will end. If it isn't with the
transition to v9.5, it will be the transition to 9.6. At this point, all
of the issues you point out will still exist. There will still be people
who are running multiple versions, there will still be people who failed
to read or comprehend the impact of the change. All that the transition
does is delay the pain point while adding additional complexity to the
code base. Admittedly, in this case, the additional complexity is very
small.

I would certainly agree that we should try to make the error message as
informative as possible. However, that should be a general aim anyway
and if the error messages are not sufficiently informative, they should
be improved. Poor error messages are frequently a greater source of
frustration than unexpected change. Today I have been fighting with a
javascript library where the error message literally just says "Failure"
- absolutely pointless error message which adds nothing. In fact, it
would be better if there was no error handler and it just crashed with a
stacktrace. 

This is a change in the transition to a new major version. I think users
should be prepared for breaking changes when upgrading to a new major
version. If it was a minor version change, a transition would be
mandatory. . 

A transition period also delays the goal for this change i.e. to improve
consistency in terminology and concepts.