On 31/01/2013 6:44 p.m., Alex Rousskov wrote:
On 01/30/2013 06:30 PM, Amos Jeffries wrote:
I've kind of gone off the idea of leaving old code using a wrapper API
with the old behaviour. All that we have got out of that approach is
added technical debt for others whoc have to ome along afterwards and
learn two API interfaces then decide which ne to remove
I agree that adding a conflicting API is bad, so I would like to add a
fourth step to my sketch:
4. Upgrade all users of eventDelete(f,a) API that currently supply a
non-NULL second argument to use new eventDelete() that supplies an async
call (from step #1). If possible, convert all other eventDelete users to
the new eventDelete(). If not possible, rename the old two-argument
eventDelete(f,NULL) to a single-argument eventDeleteAll(f) call.
This fourth step will eliminate or, in the worst case, minimize doubts
and conflicts for future API users.
It is far better, easier, simpler, safer to have the one person who
understands the change properly, replace all the existing API fuctions
in one polish patch. This will also teach them if there is some weird
caller hidden somewhere that breaks under the new design. AND, will
assist with portage by causing build errors when the API from newer code
is not converted to the older versions required API.
Agreed. Unfortunately, it is often the case that the "one person who
understands the change properly" is nowhere to be found, too busy, is
viewed as disrupting attempts to fix something by others, and/or
multiple people think they understand the change properly, but their
understanding differs :-).
Interesting definition of "one" you have there.
I was speaking about the time of initial API change. The points you
highlight as issues down the track are all caused by broken or inomplete
API transitions, which a lot of the time are caused directly by doing
the transition with wrappers.
Amos
