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

[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