Re: [PATCH] commit: Add commit_list prefix to reduce_heads function.

[Jonathan Nieder <jrnieder@gmail.com>]

Thiago Farina wrote:

> Signed-off-by: Thiago Farina <tfransosi@gmail.com>

I know that the context is part of an effort to make the commit_list
functions into something more of a self-contained API, but the
reader does not know that.  Perhaps you could say some words about
that in the change description: what's wrong with the current
situation, what context does this change come from, and what positive
effect would it have?

Beyond that, I must say I do not think this goes far enough to seem
useful.  If I wondered what reduce_heads did, wouldn't
commit_list_reduce_heads be even more confusing? (ignoring the typo)

Perhaps a more natural way to proceed would be as follows:

 . first, collect the functions to be treated as a module and
   list them in Documentation/technical (in this case, perhaps
   api-revision-walking or a new api-commit-list)

 . next, describe their current meaning.  If this requires
   apologizing for the name, that's a good hint that a name
   change might be worthwhile

 . finally, tweak signatures (names and arguments) based on the
   results from step 2 and update the documentation at the same
   time.

That way, people used to the current functions would at least have
some documentation to help them adjust.  What do you think?