Bastien <b...@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"
