Re: [PATCH] Rename headline to heading

[Bastien]

Hi André,

André A. Gomes <andremegafone@gmail.com> writes:

> 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.

Yes, that's what I suggest too.

> 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?

In general yes, but for this change, I find it easier to review and to
test the change with the plan I suggested: 1) only documentation-fixes
then 2) internals with no impact on the user then 3) internals with
impact on the user.

> 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.

I think you can send just patches for the three steps, I'd rather avoid
creating a remote branch just for this.

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

Thank you for this (parly boring but needed) work!

-- 
 Bastien