[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] Rename headline to heading
From: |
André A . Gomes |
Subject: |
Re: [PATCH] Rename headline to heading |
Date: |
Thu, 30 Sep 2021 15:21:50 +0300 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) |
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"