Nuutti Kotivuori <naked@iki.fi> writes:
> Now, I am not saying that deprecating the non-'2' variants of the
> functions would be strictly wrong. There are many ways to look at the
> matter and many ways to view deprecation - but these are my views on
> the matter.
>
> To me, deprecation an awfully strong tag when placed on a function. It
> is something that should chime a warning immediately. It is like
> saying that "You should not be using this function."
That's the idea. We want people writing new code to use the new API,
unless they're explicitly trying to be compatible with older
Subversions.
> But there is a reason to keep on using that function. Considering the
> APR versioning guidelines, it is quite okay to write code against 1.1
> headers that works okay on 1.0 if you don't use any of the new
> features provided by the 1.1 API. Hence everything the 1.1 API
> provides should be just that - additional functions that you can use
> if you want to take advantage of the *new* features, knowing that you
> are then dependant on that minor version.
Anyone who wants/expects their code to compile against 1.0.x needs to
test it with 1.0.x. The whole reason we have these guidelines is so
people will know what's promised and what's not. We didn't promise
that writing against the 1.1 API will automatically work with 1.0.
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.
The problem you describe can be solved by simply documenting the facts
(as you recommend yourself, a bit farther on in your post...).
> And like already mentioned, deprecation usually means that function
> will be removed in the near future. Specifying that this only means
> the current form of the function, and not that the function name is
> going away, is confusing to people who use the library.
I grant that it's confusing, until one understands that "2.0" means
"full reset". When that happens, we can easily publish a table
showing how to adjust calling code.
> As a solution to the problem, I propose just being a bit more verbose
> and not using the deprecated tag.
>
> 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.
> As for the actual naming issue when a function interface is "improved"
> - it can be argued both ways. Descriptive names such as *_depth point
> out exactly what can be expected of the new functions, which is an
> important point in my opinion. Coming up with descriptive suffixes can
> be hard, though. Then again, naming them *2 underlines the fact that
> they are just newer revisions of the same functions, and there is
> never any question which alternative is the latest and greatest. But
> it is not descriptive at all and people might have a harder time
> deciding if they want to use the older or newer function.
We should decide on a case-by-case basis. (See my comments in issue
#1552, for example.)
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.
-Karl
P.S. I've held off putting anything in HACKING about this until the
thread reaches some sort of obvious consensus :-).
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Wed Mar 17 04:33:56 2004