kfogel@collab.net wrote:
> Nuutti Kotivuori <naked@iki.fi> writes:
[...]
> I think if we use your interpretation, the burden on development is
> simply too great. We've been very clear about what's guaranteed and
> what's not; let's not impose more burden on ourselves for the sake
> of an entirely avoidable use case.
"Hmm... Okay, I can relate to that." :-)
>> Simply explaining the situation in the documentation will give the
>> users the best grounds on making the decision over using the newer
>> function and forfeiting older minor version compatibility or just
>> sticking with the old - and also giving them an idea what is going
>> to happen in the future. As an example, in the WC administrative
>> directory lock depth case, the documentation string could simply
>> point the user to a respective svn_wc_adm_foo2 function, point out
>> that it was added since 1.1.0 (or development leading to 1.1.0) and
>> that 2.0 will most likely have the svn_wc_adm_foo function with the
>> parameters of svn_wc_adm_foo2.
>
> Sure! We should continue using "@deprecated", because it gives us a
> well-defined string to search for. But there's no reason the
> additional documentation can't be present. It can only help. That
> way if someone *wants* to write compatibly with the 1.0.x API, they
> can do so, even if only 1.1.x is present on their system.
On that note, we should probably start using "@since 1.1" (or 1.1.0,
if that is preferred) on every new function (or thing) added to the
interface - and probably nuke all those tags at 2.0, since it won't
matter then anymore and it is just clutter.
> Using "2" makes sense when it's a straightforward updating of an old
> API whose name was fine. But when the function's meaning is
> changing significantly, or when the old name is agreed to be
> unsatisfactory, then we can simply choose a better name, with no "2"
> suffix.
>
> Either way, the old, deprecated function can refer to the new one.
Agreed.
> P.S. I've held off putting anything in HACKING about this until the
> thread reaches some sort of obvious consensus :-).
Well, I still consider the approach here unconventional, but by no
means unsound. So as long as it is documented, it's all rose petals
and vanilla ice-cream.
-- Naked
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Wed Mar 17 05:32:16 2004