Naming of function versions (Was: Re: [PATCH] Re: The new svn_wc_adm_*_depth functions.)

[Nuutti Kotivuori <na...@iki.fi>]

D. J. Heap wrote:
> After thinking about it some more, I still like the '2' variant idea
> and then resetting them back to the normal name in a major version
> change -- but as a client it does seem a bit confusing.  That is,
> the functions that are marked deprecated are not actually going to
> be removed.  In fact, they will become the preferred function again
> with a slightly different parameter list and the '2' variants (which
> were not deprecated) will be removed.
>
> I don't have a better idea, but it does seem a little odd to me.
> Maybe just add a more detailed note about this to the doc comments
> or something?

Well, I personally don't like naming functions with a '2' suffix too
much, but regardless of that, I think the deprecation needs a bit more
thought.

I will quote a few paragraphs from the APR versioning document for
reference:

,----[ Replacing functions ]
| This gets a bit trickier. The original function must remain
| available at the link-level so that an application compiled
| against a minor version will continue to work with later minor
| versions. Further, if an application is designed to work with an
| earlier minor version, then we don't want to suddenly change the
| requirements for that application. This means that the headers
| cannot silently map an old function into a newer function, as that
| would turn an application, say, based on 1.2 into an application
| requiring the 1.4 or later release.
| 
| This means that functions cannot truly be replaced. The new,
| alternate function can be made available in the header and
| applications can choose to use it (and become dependent upon the
| minor release where the function appears).
| 
| It is possible to design a set of headers where a macro will
| always refer to the "latest" function available. Of course, if an
| application chooses to use this macro, then the resulting
| compiled-binary will be dependent upon whatever version it was
| compiled against. This strategy adds the new functionality for
| applications, yet retains the necessary source and binary
| compatibility for applications designed or built against previous
| minor releases.
`----

,----[ Deprecating functions ]
| ...
|
| Note that all deprecated functions will be removed at the next major
| version bump.
`----

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

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.

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 would like to use deprecation only for functions that have a strong
point against using them - something like that they will not work as
expected, or have security implications or whatever. Functions that if
Subversion library users find themselves using, they should consider
carefully the alternatives, even if it might mean that they will
require a newer minor version to work after that.

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.

But most importantly, it still drives the point home and does not make
anyone jumpy over the deprecation issue.

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.

-- Naked

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Naming of function versions

[Travis P <sv...@castle.fastmail.fm>]

On Mar 18, 2004, at 7:45 AM, D.J. Heap wrote:

> Nuutti Kotivuori wrote:
> [snip]
>> No, I don't think you have. I just haven't seen any project where
>> deprecated functions would have not disappeared in a following major
>> release, but instead become the supported functions again. Also, I
>> don't believe I have seen the something2 naming for new functions
>> anywhere. So I would not call those methods conventional. But that may
>> ofcourse be just me.
>> -- Naked
>
> FWIW, the something2 naming is all over the place in MS API's -- 
> especially COM interfaces.  They also used to use somethingEx, but 
> mostly stopped doing that as there is nowhere to go after 
> that...somethingExEx?
>
> Hardly makes it a standard, of course, but at least it's not 
> unprecedented.
>
> DJ

It's certainly not unprecedented.  Using Apple's Toolbox library on 
GS/OS (Apple IIgs) circa 1987, NewWindow2 was introduced with much more 
functionality than NewWindow.  I would not be surprised if the 
Macintosh Toolbox had the same type of thing though I wasn't 
programming Macs at that time but the GS/OS Toolbox was clearly highly 
related to the Mac version.  Both continued to be supported.

-Travis


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Naming of function versions

["D.J. Heap" <dj...@shadyvale.net>]

Nuutti Kotivuori wrote:
[snip]
> 
> No, I don't think you have. I just haven't seen any project where
> deprecated functions would have not disappeared in a following major
> release, but instead become the supported functions again. Also, I
> don't believe I have seen the something2 naming for new functions
> anywhere. So I would not call those methods conventional. But that may
> ofcourse be just me.
> 
> -- Naked
> 

FWIW, the something2 naming is all over the place in MS API's -- 
especially COM interfaces.  They also used to use somethingEx, but 
mostly stopped doing that as there is nowhere to go after 
that...somethingExEx?

Hardly makes it a standard, of course, but at least it's not unprecedented.

DJ

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Naming of function versions

[Nuutti Kotivuori <na...@iki.fi>]

Greg Hudson wrote:
> It's not really fair to call our approach "unconventional" when
> there is no convention to follow.  (Certainly there's none that I'm
> aware of.)

Ah, a mere linguistic mistake on my part I guess. I just meant that it
was not conventional, not that it would be going against a convention.

And you are right, there probably isn't a convention on how such
things are done with programs abiding to the APR versioning document,
since it is stricter than many others.

-- Naked

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Naming of function versions

[Greg Hudson <gh...@MIT.EDU>]

On Thu, 2004-03-18 at 08:16, Nuutti Kotivuori wrote:
> No, I don't think you have. I just haven't seen any project where
> deprecated functions would have not disappeared in a following major
> release, but instead become the supported functions again. Also, I
> don't believe I have seen the something2 naming for new functions
> anywhere. So I would not call those methods conventional. But that may
> ofcourse be just me.

It's not really fair to call our approach "unconventional" when there is
no convention to follow.  (Certainly there's none that I'm aware of.)


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Naming of function versions

[Nuutti Kotivuori <na...@iki.fi>]

Greg Stein wrote:
> It isn't "simply too great". It just isn't possible. If you compile
> against 1.1.x, then your application *requires* 1.1.x. There isn't
> anything that you can do unless you lift the hood and dig very very
> hard to ensure that your app can bind/work against 1.0.x.
>
> The simplest example is a #define constant changing from 1.0.x to
> 1.1.x.  That changing value can then make a particular function
> alter its behavior. It would know whether a 1.0.x or a 1.1.x user is
> calling it.  This kind of change in the constant is acceptable under
> the guidelines.

Um, the APR versioning text seems to explicitly disallow changes to
constants. It also says "Further, if an application is designed to
work with an earlier minor version, then we don't want to suddenly
change the requirements for that application. This means that the
headers cannot silently map an old function into a newer function, as
that would turn an application, say, based on 1.2 into an application
requiring the 1.4 or later release." And even more "It is possible to
design a set of headers where a macro will always refer to the
'latest' function available. Of course, if an application chooses to
use this macro, then the resulting compiled-binary will be dependent
upon whatever version it was compiled against. This strategy adds the
new functionality for applications, yet retains the necessary source
and binary compatibility for applications designed or built against
previous minor releases."

I don't know, maybe I am just reading the guidelines through my own
set of tinted glass, but I read the minor version constraints as such:

 - Application coded originally against 1.0 headers is source and
 binary compatible against later minor versions, but also that
 application compiled against 1.1 headers is still binary compatible
 with 1.0 libraries, if there are no library versioning issues on the
 OS level.

 - Application coded against 1.1 headers, but without using any 1.1
 specific features, is still source and binary compatible against 1.0,
 regardless whether it has been compiled against the 1.1 headers or
 1.0 headers.

If this is *not* so, then obviously all that I have been talking here
is about princesses and toads.

> Something built against 1.0.x must continue to function with the
> 1.1.x libraries (and the guidelines are defined to enable this), but
> the reverse does not hold true. If you install a 1.1.x application,
> then the libraries must be upgraded to 1.1.x. The theory here is
> that an administrator can feel safe doing the upgrade because it
> will not break any existing 1.0.x applications.

The upgrade mentality is sound, yes. But I always saw that applying to
only applications that actually use the 1.1 specific features, and not
just being compiled or coded against 1.1.

>> 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.
>
> Unconventional? What aspect? I must have missed an earlier post of
> yours :-)

No, I don't think you have. I just haven't seen any project where
deprecated functions would have not disappeared in a following major
release, but instead become the supported functions again. Also, I
don't believe I have seen the something2 naming for new functions
anywhere. So I would not call those methods conventional. But that may
ofcourse be just me.

-- Naked

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Naming of function versions

[Greg Stein <gs...@lyra.org>]

On Wed, Mar 17, 2004 at 06:31:55AM +0200, Nuutti Kotivuori wrote:
> kfogel@collab.net wrote:
> > Nuutti Kotivuori <na...@iki.fi> writes:
> 
> [...]
> 

[ in reference to "avoid 1.1 functions so your code works against 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.

It isn't "simply too great". It just isn't possible. If you compile
against 1.1.x, then your application *requires* 1.1.x. There isn't
anything that you can do unless you lift the hood and dig very very hard
to ensure that your app can bind/work against 1.0.x.

The simplest example is a #define constant changing from 1.0.x to 1.1.x.
That changing value can then make a particular function alter its
behavior. It would know whether a 1.0.x or a 1.1.x user is calling it.
This kind of change in the constant is acceptable under the guidelines.

Something built against 1.0.x must continue to function with the 1.1.x
libraries (and the guidelines are defined to enable this), but the reverse
does not hold true. If you install a 1.1.x application, then the libraries
must be upgraded to 1.1.x. The theory here is that an administrator can
feel safe doing the upgrade because it will not break any existing 1.0.x
applications.

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

Agreed.

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

With the caveats mentioned above. Whatever you compile against will
determine what you must link/run against. If you code to the 1.0.x API and
build against it, then you can run on a system which has 1.x.y libraries
installed.

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

Absolutely agreed. ++1.

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

Unconventional? What aspect? I must have missed an earlier post of yours :-)

Cheers,
-g

-- 
Greg Stein, http://www.lyra.org/

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: Naming of function versions

[Nuutti Kotivuori <na...@iki.fi>]

kfogel@collab.net wrote:
> Nuutti Kotivuori <na...@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

Re: Naming of function versions (Was: Re: [PATCH] Re: The new svn_wc_adm_*_depth functions.)

[kf...@collab.net]

Nuutti Kotivuori <na...@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