Re: [PATCH] Rename headline to heading

["André A. Gomes" <andremegafone@gmail.com>]

Bastien <bzg@gnu.org> writes:

> Hi André,
>
> I agree this change is a welcome improvement: thanks a lot for working
> on this patch.  I would like to suggest a step by step approach:
>
> 1. Updating occurrences in the documentation: manual, guide,
>    docstrings, worg occurences, etc.
>
> 2. Updating Org internals without impacting users' configuration
>    (i.e. update the functions and variables name, but don't update
>    the "file+headline" config string.)
>
> 3. If the "file+headline" config string is the only part of a config
>    that can be impacted by this change, support both the new and old
>    strings for backward compatibility.
>
> We don't need a transition period for the first two changes, and we
> don't need one either for the third one if we implement the backward
> compatible solution.  We need a transition period if we remove it, but
> I'm not convinced removing it is really needed now.
>
> What do you think?

Hi Bastien,

Sorry for my late reply.

Overall, I agree with the suggested approach.

Here's something I wasn't sure about when I worked on it.  How should I
distribute the changes commit-wise?  Tom Gillespie, for instance,
suggested separating documentation and docstring from internals.

I think it's ok to separate internals from documentation (manuals).  But
when it comes to docstrings, it feels a bit odd.  Say there's a function
named foo-headline whose docstring contains the string headline.  Then
there would be a commit where the function continues to have headline in
its definition, but the docstring contains heading.  Shouldn't we avoid
such a "grey area" snapshot?

I could create a bunch of small and well documented patches, that in the
end would be squashed before merging into master.  Perhaps it would even
make sense to have a branch for a while so that people would test it.
This way everyone gets a fine grain for inspection, while in the end we
get a huge "/s/headline/heading" commit.

If someone has better ideas, please share.  I will take a look at this
perhaps next week.  Thank you.


-- 
André A. Gomes
"Free Thought, Free World"